Get started with webhooks

Security

Deel secures webhook notifications by signing each payload with an HMAC generated using SHA256 and a unique secret key that you receive when you create a webhook subscription.

Here’s how it works:

1. Signature generation: When a webhook event is triggered, Deel uses your secret key and the SHA256 algorithm to compute a digital signature of the payload (using a POST prefix). This signature is then included in the x-deel-signature header of the webhook request.
2. Signature verification: On your side, you should calculate the HMAC of the received payload using the same secret key and compare it with the signature provided in the header. If they match, the webhook is verified as authentic.

By verifying the signature, you can be confident that the webhook originates from Deel and that the payload hasn’t been altered during transmission.

Prerequisites

• A Deel account with API access
• Basic familiarity with webhook concepts
• A secure HTTPS endpoint to receive events

Event types

We maintain a list of webhook event types in our developer portal, but you can also access the available endpoints using the API. Pick the one that best suits your needs:

• Article with all webhook event types
• Get all webhook event types API endpoint

Webhooks API

You can use the webhook API to manage your webhooks. The following endpoints are available:

• List webhook event types
• Create a webhook
• List webhook subscriptions
• Retrieve a single webhook
• Edit a webhook
• Delete a webhook

📘

Webhooks API scopes

Unlike Other API endpoints, webhook subscription endpoints do not require specific scopes.

Webhook structure

Webhook headers

In addition to the message payload, each webhook message has a variety of headers containing additional context.

x-deel-signature: e4fce40e4a4aa76156f8846e93193b2de5649eed7aeedf4f53abd86113c91744
x-deel-hmac-label: New Webhook
x-deel-webhook-version: 1.0.0

The following header fields are used:

Webhook body

The webhook payload body includes a data object with the following information:

• Meta object
• Resource object
• Timestamp property

Meta object

The meta object includes the metadata for the webhook. The following fields are in the meta object:

Resource object

The resource object includes the data of the actual resource for the webhook. For example, if the webhook event is for contracts, the resource object will include data from the contract.

Timestamp property

Defines the timestamp when the webhook was created.

Testing webhooks

You can also test your webhooks locally using tools that forward webhooks to your local server. While we're not affiliated to any of them, here's some tools you can use:

• Hookdeck
• Smee

Best Practices

When using webhooks, it's important to follow some best practices:

• Respond fast
• Ignore duplicates
• Stick to your needs
• Implement reconciliation jobs

Respond fast

By ensuring your webhook receiving mechanism reliably returns a 2xx response, you can avoid delivery failures and the subsequent disabling of your webhook subscription.

Non-delivered webhook messages are stored in a message queue and retried later. Responding promptly reduces the chances of requests timing out and delivery failures. For more information, see Retry mechanism.

Ignore duplicates

Webhook endpoints may occasionally receive the same event more than once. You are advised to guard against duplicated event receipts by making your event processing idempotent. You can do this by logging the events you’ve processed and not processing the already-logged events.

Stick to your needs

Only subscribe to the event you are using. For example, if you only need to know if the contract has been created, subscribe to that event only. You should make judicious use of the services.

Implement reconciliation jobs

You shouldn’t rely solely on receiving data from the webhooks, as delivery isn’t always guaranteed. We recommend that you also implement reconciliation jobs to fetch data from Deel periodically. For example, if you are awaiting contract status updates, you should also implement a reconciliation job that pulls data from Deel API periodically to ensure that you are getting all the updates correctly.

Retry mechanism

If a webhook delivery fails—that is, if your webhook URL responds with a non-2xx HTTP status—the message is not immediately discarded. Instead, it’s queued for a series of 9 automated retries using an exponential backoff schedule.

After the 9th retry, which is the 10th attempt in total, the webhook is marked as disabled and no further events will be sent.

When a webhook is disabled, we send an email notification to the organization admin.

You can re-enable the webhook if you need, but keep in mind that URLs cannot be edited.

Retry schedule

For example, the retry delays are typically set as follows:

📘

A background cron job runs every 10 minutes to process these retries, so actual retry times might be adjusted to the next cron execution.

Unique webhook URLs

If the webhook URL itself is no longer valid or has permanently changed, you cannot update the URL of an existing subscription. In that case, you must create a new webhook subscription. For more information, visit Managing webhooks.