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’sdevelopment and production environments respectively.
Configuring webhooks
Once you have added endpoints on your server, add these endpoint URLs in your Knot Dashboard here. You can configure up to 10 webhook URLs per environment. You can also manage webhook URLs programmatically, for example from an AI agent, with Create Webhook Endpoint and related endpoints. These endpoints use Agent Authorization with a short-lived access token that you approve through the Knot Dashboard, rather than Basic Authentication with yourclient_id and secret.
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/32. This IP address is subject to change. Knot notifies you 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. If your webhook receiver also requires an API key or token header, the Knot team can configure a custom header name and value for your endpoints.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.Prepare the hash map
Collect the following headers and body fields into a hash map.
Content-Length is the byte length of the entire raw JSON request body. Any tampering with the body (beyond the signed event and session_id fields) will therefore change this value and invalidate the signature.Not all webhooks 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.Build the signature
Build the following string from the hash map, concatenating key-value pairs with Using your client secret from the Knot Dashboard, compute an HMAC signature using SHA256 and base64 encode the result.
|Retries
If there is a non-200 response or no response within 10 seconds from your webhook listener endpoint, Knot retries 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. Knot includes this metadata in all webhook payloads for that session. This is useful for:- Conditional webhook acceptance: Pass a JWE token whose contents you can use 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:Webhook payload
When metadata is attached to a session, it appears in thedata.metadata field of webhook payloads:
Metadata is only included when you provide it. If no metadata is attached to the session, the
metadata field doesn’t appear in the webhook payload.Constraints
- Maximum 10 keys per session
- Maximum 500 characters per value
- Keys and values must be strings