Webhooks allow your software to be updated when an event occurs in Finch.
Finch will send a HTTP POST web request to your notification URL when the event occurs which encloses a JSON message describing the event which has occured.
You can subscribe to the following events:
How do I create a webhook subscription?
The webhook you require needs to be registered in Finch.
To register your webhook, please email our team.
For each webhook, we will require:
- Your notification URL, which must be HTTPS.
- Which events you would like to subscribe to, as referenced in our documentation.
Our team will update you when your webhook has been created, and we will enclose your webhook secret.
How do I secure my notification URL?
All Finch notifications contain the following fields:
| Field | Data type | Description |
|---|---|---|
| id | string (uuid) | A UUID of the webhook request |
| alg | string | Protection algorithm of the signature |
All Finch notifications contain the following HTTP headers:
| Header | Description |
|---|---|
| bt-signature | The Base64 encoded hash (using the signature algorithm specified in the "alg" field) of the request body |
Finch currently uses HS256 (HMAC-SHA256) for the signature algorithm using a shared webhook secret, which is a string. Use UTF8 encoding for the secret and request body. Finch will notify all webhook subscribers in advance of any proposed algorithm change.
To protect your notification URL, you should check that your calculation of the signature matches the webhook notification signature.
For example (in psuedo code), if the algorithm is HS256:
genuineNotification = webhookNotification.requestHeaders["bt-signature"] === Base64Encode(HS256(rawRequestBody, webhookSecret))
Depending on your application security requirements, you may also make a record of the notification id to prevent replays.
What is the webhook retry policy?
We consider a webhook as having been successfully delivered when we receive a success status code (2xx) from your webhook URL.
If we receive any other status code (for instance, if your API is temporarily unavailable), we will start retrying. We use jittered exponential backoff for the retries. We will keep retrying for up to five and a half hours over 14 attempts.
How do I end a webhook subscription?
To cancel a webhook subscription and stop receiving notifications, please email our team.
Can I see an example?
Of course. Here is an example webhook from Finch.
The webhook secret for this example is sKJ3myXpEfDL23Ub9RxjLg==
{
"recipient_id": "4ctumGoWTrWRIhmSWkvYfF",
"file_id": "2lY31RVdtK92xnNI1v1eej",
"file_reference": "LET-10082",
"id": "1Ui2V3lwhvk94u26NXfW63",
"alg": "hs256",
"sentAt": "2023-07-26T15:59:27.3986918+01:00",
"event": "dc_recipient_first_opened"
}
content-type: application/json; charset=utf-8
bt-signature: yi04anTLheRKqW8KfAB6nnQqOKgwzIo2Pm7zFeFdy1M=
curl -X 'POST' 'https://localhost/your-endpoint'
-H 'content-length: 230'
-H 'content-type: application/json; charset=utf-8'
-H 'bt-signature: yi04anTLheRKqW8KfAB6nnQqOKgwzIo2Pm7zFeFdy1M='
-H 'host: localhost'
-d $'{"recipient_id":"4ctumGoWTrWRIhmSWkvYfF","file_id":"2lY31RVdtK92xnNI1v1eej","file_reference":"LET-10082","id":"1Ui2V3lwhvk94u26NXfW63","alg":"hs256","sentAt":"2023-07-26T15:59:27.3986918+01:00","event":"dc_recipient_first_opened"}'