Overview
Webhooks are a great tool for building scalable applications as they allow you to receive updates about changes in the API without needing to check for them. A webhook will be sent to the server URL that you specified in the webhook-config related to your organization. When you receive a webhook, your server should respond with a 200 response within 3 seconds to let our server know that you've successfully received the webhook. This webhook config applies to all our products and APIs.
Consuming Webhooks
Given the brief response time, it's best to handle webhooks by adding them to your own database table and then immediately responding to the webhook server with a 200 code. You can then go through the webhooks in your own database and keep a record of all the webhooks you've received.
If we don't get a 200 response from you in time, we'll try again, increasing the time between attempts.
Setting up your Webhook-Config
Every organization is set up with a webhook-config that is off by default. To turn it on and choose what events you want to know about, you need to make a PATCH call:
PATCH: /api/v1/current-tenant/webhook-config
{
"url": "string",
"enabled": true,
"sharedSecret": "string",
"webhookTypes": [ "Payment" ]
} Webhook types:
Payment Transaction Document ExternalAccount Identity
It's important to note that you'll only receive webhooks for the types that you have added to the webhookTypes array.
Webhook security
When you're setting up your webhook, you'll come across a field named sharedSecret. This secret is used to make sure that the webhook you receive is from our server, Keyrails.
Here's how it works: The sharedSecret is used along with the contents of the webhook to create a unique code. This code is then sent in the header of the webhook. This way, we can be sure that the webhook is indeed from our server.
The process is similar to a secret handshake that only the server and your webhook know. It's a way to confirm that the webhook is genuine and hasn't been tampered with.
The code for this process is:
Base64Encode(Hmac-Sha256(sharedSecret, webhookPayload)). The result of this code is sent in the webhook header under the key X-Keyrails-WebHook-Hmac.
Updated 2 months ago