​
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 Customer 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 body fields (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 Knot secret, 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.