Webhooks for partners

As a partner, you can configure webhooks to get automated notifications of various offering events.

What are webhooks?

Webhooks are HTTP POST requests that Raiseform makes to the URL of your choice. These requests include a JSON-formatted payload with details about an event related to an Offering or Investor.

How do I configure webhooks?

Go to Account > Webhooks, then click "Create webhook endpoint". You can add up to 3 webhook endpoints. Webhooks will be sent to every endpoint you configure, for all webhook events.

What are the webhook events?

When any of the following events occurs, a webhook is sent:

  • offering.closed_failure
  • offering.closed_success
  • offering.open
  • offering.withdrawn

What do the JSON payloads look like?

Here is an example JSON payload that would be posted to your webhook endpoint: 

{
  "event": "offering.closed_failure",
  "offering_id": "456f27a1-b27d-4c90-8d26-2f53a24dce01",
  "offering_number": 5555
}

You can use the offering_id to make a Read Offering API request to get additional details.

Can webhook payloads be verified?

Yes, all webhook payloads are signed so you can verify them. You should use your webhook's "signing secret key" to generate your own HMAC, and compare it to Raiseform's HMAC included with each webhook payload. Here's how it works:

  • Get your webhook's "signing secret key".
    Go to Account > Webhooks, select a webhook, then click to show the value. It starts with ssk_.
  • Get the timestamp and Raiseform's HMAC.
    When your app receives a webhook payload from Raiseform, get the value of the X-Raiseform-Signature-512 header. (It looks like t=1761047581,v=32a19fd2945b6ddda577e7975e664d35a9b1f9f81a1544ddd459a79ec06c87dc83f2cf66c92ed6865d9a5fe438d227ac0475d37f9a0752195b0650116320b0b3.) Split the string by comma (,) to get the key-value pairs. The t key represents the Unix timestamp. The v key represents Raiseform's HMAC.
  • Build your HMAC.
    Build your HMAC using the SHA512 algorithm with hexdigest formatting. For example, in Ruby you should use OpenSSL::HMAC.hexdigest('SHA512', key, data). The "key" is your your webhook's "signing secret key". The "data" is created by concatenating the Unix timestamp, a dot/period character (.), and the JSON string from the webhook payload.
  • Compare your HMAC against Raiseform's HMAC.
    If the HMAC strings don't match, the webhook payload may not be legitimate.

If verifying the signature exceeds your technical capabilities, there is a simpler but less secure alternative. You can add a token parameter to the endpoint URL you enter in Raiseform, with a random value that you generate. Then when you receive a webhook payload from Raiseform, you check to confirm the token parameter has the value you generated. If the strings don't match, the webhook payload may not be legitimate.

Can I simulate/test webhooks?

Yes. Go to Account > Webhooks, select a webhook then click the "Test" button. For each test you can select which status you want to POST to your endpoint.

Can I see webhook results?

Yes. Go to Account > Webhooks, select a webhook then see the "last request" information, including:

  • Time
  • Event
  • Offering
  • Response status your endpoint returned