Skip to main content

​
Introduction

A webhook is an HTTP request used to provide various events. Knot provides webhooks for updates related to a user’s lifecycle in the Knot user experience as well as various asynchronous processes. To receive webhooks from Knot, set up dedicated endpoints on your server as webhook listeners that can receive POST requests from Knot’s development and production environments respectively.

​
Configuring Webhooks

Once you have added endpoints on your server, add these endpoint URLs in your Knot Dashboard here. The URLs of your dedicated endpoints must be in the standard format of http(s)://(www.)domain.com/ and must have a valid SSL certificate if https. Knot sends POST payloads with raw JSON to your webhook URL from the following IP address in all environments (Production & Development): 35.232.249.218. This IP address is subject to change and you will be notified in advance of any changes.

​
Webhook Verification

Knot signs all outgoing webhooks so that you can verify the authenticity of any incoming webhooks to your application. This verification process is optional and is not required for your application to handle webhooks from Knot.
1

Extract the knot-signature header

Extract the Hash-based Message Authentication Code (HMAC) signature included in the Knot-Signature header of the webhook. You will later compare this against your computed signature.
2

Prepare the hash map

Collect the following headers and body fields into a hash map:
const data = {
  "Content-Length": "178",
  "Content-Type": "application/json",
  "Encryption-Type": "HMAC-SHA256",
  "event": "CARD_UPDATED",
  "session_id": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584"
}
Not all webhooks will have a session_id in the request body (such as the MERCHANT_STATUS_UPDATE webhook). In those scenarios, do not include the session_id in the hash map.
3

Build the signature

Build the following string from the hash map, concatenating key-value pairs with |
Content-Length|178|Content-Type|application/json|Encryption-Type|HMAC-SHA256|event|CARD_UPDATED|session_id|fb5aa994-ed1c-4c3e-b29a-b2a53222e584
Using your client secret from the Knot Dashboard, compute an HMAC signature using SHA256 and base64 encode the result.
4

Compare the signatures

Compare the signature extracted from the Knot-Signature header in the webhook to the signature you computed in the above step and ensure they’re the same.

​
Retries

If there is a non-200 response or no response within 10 seconds from your webhook listener endpoint, Knot will retry sending the webhook up to two times with a few minutes in between each request.

​
Session Metadata

You can attach custom key-value pairs (metadata) to a session, and this metadata will be included in all webhook payloads for that session. This is useful for:
  • Conditional webhook acceptance: Pass a JWE token, the contents of which can be used to determine whether to accept or reject the webhook payload
  • Request correlation: Include internal reference IDs for tracking
  • Custom data: Any string key-value pairs you need echoed back

​
How to Attach Metadata

You can attach metadata in two ways: Server-side: Include metadata when calling Create Session: 
POST /session/create
{
  "type": "card_switcher",
  "external_user_id": "user-123",
  "card_id": "card-456",
  "metadata": {
    "reference_token": "your-jwe-token",
    "internal_ref": "order-789"
  }
}
Client-side: Pass metadata when opening the SDK. See the SDK documentation for platform-specific implementation details. Client-side metadata is merged with any server-side metadata, with client-side values taking precedence for duplicate keys.

​
Webhook Payload

When metadata is attached to a session, it appears in the data.metadata field of webhook payloads: 
{
  "event": "CARD_UPDATED",
  "session_id": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584",
  "task_id": 25605,
  "external_user_id": "user-123",
  "merchant": {
    "id": 11,
    "name": "Uber"
  },
  "data": {
    "card_id": "card-456",
    "metadata": {
      "reference_token": "your-jwe-token",
      "internal_ref": "order-789"
    }
  },
  "timestamp": 1710864923198
}
Metadata is only included when you provide it. If no metadata is attached to the session, the metadata field will not appear in the webhook payload.

​
Constraints

  • Maximum 10 keys per session
  • Maximum 500 characters per value
  • Keys and values must be strings