Using Unidy Webhooks

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

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:

1. Concatenate the registration secret and the request body
2. Hash the resulting string using SHA-256
3. 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.