Server events

In order to react to asynchronous events, you can configure a webhook in the Developers tab of the Console to receive events on your server. To do so, go to the Developers tab and then to the Webhooks page in the Console, and enter the URL where you want to receive the events. It will generate a secret that will be used to sign the requests, to make sure that the events were sent by Nabla.

To test that your webhook is correctly configured, you can send a test event to your URL. To do so, on Webhooks page, click the ... button on the row of the URL you want to test, then click on "Send a test payload".

Format

Attributes

id - string
The unique identifier of the event.

type - string
The type of the event. Each event type is build with {object}.{action_past_participle} or {object}.{sub_object}{action_past_participle} pattern.
Example: conversation.message.created
Check out the list of events types.

data - object
Data associated with the event.

Example

{
  "id": "695404b3-6ebf-4b17-9c64-fd397193e7d1",
  "type": "conversation.message.created",
  "created_at": "2022-03-22T15:19:58.780Z",
  "data": {
    "id": "51abd747-ab5b-4b61-8f28-5a41b554bd7a",
    "text": "Hello, I have some good news!",
    "created_at": "2022-03-22T15:19:58.779Z"
  }
}

Signature

Every webhook request is signed using HMAC_SHA256 signature.

The request on your dedicated endpoint will contain two headers:

  • X-Nabla-Webhook-Timestamp: an ISO 8601 formatted date corresponding to the instant the webhook has been sent.
  • X-Nabla-Webhook-Signature: Hexadecimal representation of HMAC_SHA256 signature computed from the body of the webhook and the timestamp above.

Example:

X-Nabla-Webhook-Timestamp: 2022-03-01T14:34:12.675Z
X-Nabla-Webhook-Signature: 5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Verifying the signature manually

The signature is computed using the following algorithm:

  1. Generate timestamp, an ISO 8601 formatted string.
  2. Compute the timestamped payload by concatenating timestamp and body (everything is UTF-8 encoded, no characters inserted in between). Let's call this the timestampedPayload, where timestampedPayload = timestamp + body and body is the raw string representation of the HTTP body as received by your endpoint.
  3. Then, we have signature = HMAC_SHA256(<YOUR_WEBHOOK_SECRET_KEY>, payload).digest('hexadecimal'). We use an hexadecimal digest.

Each time you receive a request you should verify that the signature is valid. You should recompute the signature using the same algorithm and check that the value is equal to the one in the X-Nabla-Webhook-Signature header.

To prevent replay attacks, you should also check that the value of the timestamp is close to the current time.

If the timestamp is too old or if the signature is not valid, you should ignore the request.

Retry mechanism

If your server does not answer with an HTTP status code of 200, Nabla will consider that the request has failed and will retry it later. A failed event will be retried during at most 5 days.

You can see the history of webhook events in the "Webhook events" page of the "Developers" tab on the Console. The status of each event is displayed, and you will be able to retry any of them on demand.