One way to connect your systems to Unidy is by receiving webhook notifications when an event happens in Unidy. On the receiving end you need an HTTP endpoint listening to POST requests containing the event payload in JSON format in their body. This allows you to trigger custom actions or to synchronize data.
Provide the URL and the list of events you wish to be notified on to customer support so they can set up a webhook registration for you. Once your webhook endpoint has been registered Unidy sends webhooks to that URL.
Processing Incoming Webhooks
When receiving webhooks there are several things to keep in mind:
- In order for a webhook delivery to be considered successful your endpoint must reply with a
200
-299
HTTP status code within 2 seconds - Unidy will retry deliveries up to 25 times on any other status response. The timespan between the deliveries will increase with each failure. The last retry will be done after 21 days.
- Validate a webhook's signature! Customer support is going to supply you with a secret when they set up your webhook's registration. This way you can be sure the payload you received was sent by Unidy and has not been tampered with. See below section on how to check the signature
Webhooks are rate limited to 60 requests per second.
Verifying the Signature
Unidy signs event payloads before they are sent to your webhook
endpoint. This way you can ensure that the payload you received was sent
by Unidy and has not been tampered with. The webhook's signature is
passed in the UNIDY-WEBHOOK-SIGNATURE
and UNIDY-WEBHOOK-VERSION
headers.
The current signature version is 1
.
The signature itself is a SHA-256 hash of the secret concatenated with the raw request body. To verify this signature, perform the following steps:
- Concatenate the registration secret and the request body
- Hash the resulting string using SHA-256
- Compare the hex string hash value to the signature
If they're equal then this request has passed validation. If these values do not match, then this request may have been tampered with. You should not act on this request.
Webhooks Request Headers
Webhooks are sent with headers which include some more information about the webhook such as version and number of attempts.
Header | Description |
unidy-webhook-delivery-id | ID of the delivery |
unidy-webhook-delivery-attempt | Retry counter. Will increase with every attempt |
unidy-webhook-version | Version number (Signature hash and body might change in different versions) |
unidy-webhook-signature | Webhook signature (Use to ensure payload was not tampered) |