Accepting webhook requests

How do accept and handle webhook events.

Configuring a Callback URL

The webhook callback URL used for an event subscription needs to be configured on the your system to accept an HTTPS POST request in JSON format. After verifying the request signature provided in the headers, the preconfigured endpoint needs to return a 200 (OK) or 201 (created) HTTP response code to the Webhooks API request made using the domain. All webhook requests come from this domain which must be whitelisted on your system for further authentication.


Webhook authentication

Verify the webhook signature before handling the request.

Webhook event examples

  "event": "kyc.verification.success",
  "customer_id": "931e2341-c3eb-4681-97d4-f6e09d90da14",
  "occurred_at": "2021-10-20T10:27:20.154286+00:00"
  "event": "kyc.verification.failure",
  "customer_id": "931e2341-c3eb-4681-97d4-f6e09d90da14",
  "occurred_at": "2021-10-20T10:35:34.781911+00:00"

Event Handling

The request from Bond Studio to the your system contains the event subscription as the body. This provides all the relevant information concerning this event. The event enum label is also shown, as seen in the example below.

    "event": "event.label",
    "customer_id": "customer_uuid",
    "verification": "verification_status",
    "occurred_at": "timestamp",

Events should be processed and recorded following your business logic. In rare cases, the event may be received more than once, so event processing should be idempotentidempotent - Has the same result when called multiple times with the same idempotent key. One way to accomplish this, is to not process any events that have already been received and logged.


Handling duplicate webhooks

Use the combination of occurred_at and event to match a webhook that your server receives with one that you have already processed to identify a possible duplicate.

Signature Verification

The request from the Webhooks API to the developer's system also contains the Bond-Signature header used for verifying the request. The request should only be processed if the signature can be verified. This header contains a timestamp t formed at the time of the request and the signature digest of fixed version v1. An example of this header is shown below.


The signature digest is generated using keyed-hashing for message authentication HMAC, using the SHA-256 hash algorithm. For details, see the implementation of the hmac module in Python's standard library. You should calculate and verify the signature digest before processing the request.

The signature digest is calculated by encoding the webhook secret provided during event subscription, the timestamp t found in the header, and the event payload, all as byte strings using UTF-8 encoding. The procedure for doing this is as follows:

  1. Encode the webhook secret.
  2. Encode the concatenation of the timestamp t as a string, the character ., and the event JSON payload (the request body) as a string.
  3. Compute an HMAC using SHA-256 from the encoded webhook secret and encoded string from step 2.
  4. Compare this calculated signature digest with v1 from the header.

If the computed digest matches the provided digest, then the request can be processed.

Error handling

If a 200 or 201 response code is not received, the Webhooks API retries the request using exponential backoff for up to three days. This adds up to approximately eight retry attempts until a successful response is returned.

If you see that your server is not responding with 200 or 201 for webhooks, check which events are not being accepted by your server.

Did this page help you?