Learn about webhooks generated by the Cadana platform.
Cadana API Platform - Webhooks
Webhooks are automated messages sent by Cadana when actions are taken on our platform. They have an information-bearing payload and are sent to a unique URL.
Webhook Structure
All webhooks will follow the following following:
| Field | Description |
|---|---|
| eventType | The type of the event e.g person.created |
| id | a unique uuid for the webhook. This UUID should be used to dedupe on the consumer end. When a webhook is retried, it is sent with the same id |
| timestamp | The timestamp of the webhook |
| version | version of the webhook |
| data | This field will contain the specific payload of the event. See the section below for example payloads for the various events. |
{
"eventType": "person.created",
"timestamp" : 1681006175
"data": {
...
},
"id" : "e13b9e14-c062-42ea-8563-8fc9223b29b5",
"version" : "v0"
}
Headers
svix-signature: v1,CRguzeYczZmJDu/QFV8FKvJ/FHJ+iVyRbfVo6Vi5qIo=
| Header | Use |
|---|---|
| svix-signature | SHA256 signature of the webhook. See the security section for more details on how to use it properly. |
| svix-id | The unique id provided by out webhooks service provider. |
| svix-timestamp | Timestamp of the webhook. |
Best Practices
- Respond promptly: Upon receiving a webhook, it is important to respond quickly with a 200 OK status code. This helps ensure that the request is not timed out and avoids failures in Cadana webhook delivery. The payload should be stored in a message queue for processing.
- Ignore duplicates: Webhook endpoints may receive duplicate events, so it is recommended to make your event processing idempotent. This can be done by logging the unique ID field of each webhook and not processing already-logged events.
- Get the latest resource: It is a good practice to fetch the latest version of a resource when processing a webhook. For example, for a payroll.status.updated webhook, you can call GET /payrolls/{payrollId} to ensure that the latest data is being used.
- Implement reconciliation jobs: Webhook delivery is not always guaranteed, so it is important to implement reconciliation jobs to periodically fetch data from Cadana. This helps ensure that your data is up-to-date even if there are issues with webhook delivery.
Getting Started
Create a subscription in Admin App
Use the following steps to register a webhook endpoint in the Developers Center.
- Navigate to Settings → Developers and go to the Webhooks tab.
- Click on the 'Add Webhook' button.
- Specify the endpoint to which you would like to receive live Cadana events.
Handle Webhook events
After you register an endpoint, Cadana sends an HTTP POST request to the URL specified every time that event occurs. The HTTP POST request's parameters contain the JSON data relevant to the event that triggered the request.
Verify the webhook
Before you respond to a webhook, you can verify that the webhook was sent from Cadana by calculating a digital signature.
Each webhook request includes a hex-encoded svix-signature header, which is generated using the app's signing key along with the data sent in the request. Learn more about verifying signatures.
Respond to the webhook
Your application should send a 200 OK response to acknowledge that it has received data. Any response outside of the 2XX range, including 3XX HTTP redirection codes, indicates that you didn't receive the webhook.
Cadana doesn't follow redirects for webhook notifications and considers them to be an error response.
Security
Cadana uses SHA256 Webhook Signature Verification for security.
Securing a Webhook involves the verification of the Webhook source and destination and the validation of the payload (Message Content). Among different webhook authentication strategies available, signature verification stands out as the strongest form of protection for securing webhooks.
Verify signatures
Refer below image to understand the signature verification in the following steps:
Source: hookdeck.com