Webhooks are automated messages sent by Deel when something happens on our platform. They have an information-bearing payload and are sent to a unique URL. Webhooks are almost always faster than calling Deel API and require less work on your side.

For example, if you want to keep the contract information up to date between Deel and your platform, you will rely on calling Deel API every few hours to retrieve the latest state of contracts, also known as polling. Webhooks enable you to subscribe to a change event in Deel and be notified when the data is updated.

Polling vs. Webhooks

(Source: Svix)

Polling: API polling is the process of repeatedly sending requests to the same endpoint and comparing subsequent responses you receive to determine if there is updated information.

Webhooks: A webhook is a reverse API or server-to-server push notification. They work by sending out an HTTP request to a specified endpoint when an event is triggered.

Polling can be resource-intensive and you need to make calls on whether the efforts will be fruitful or not. This is not the case for webhook requests, which are only made when there is new information.

For example, if 10,000 users poll the API every 5 seconds, your API will have to be able to handle up to 10,000 requests per second, depending on the timing of the requests.

When to use polling?

You should only use polling if you meet two conditions:

You don't need updates in real time.
Updates are very frequent.

When both of these are true, polling is a very good solution because you won't have wasted API calls, and sending webhooks for every event would be highly resource-intensive.

When to use webhooks?

If you need updated data in real-time or updates are not very frequent, webhooks are the perfect solution.

Deel webhooks

The following definitions explain Deel webhook concepts:

Webhook: A single event message. Deel sends a webhook to an app's webhook subscription endpoint. A webhook contains a JSON body and metadata in the headers.

Webhook subscription: A persisted data object that an app creates using the Deel API which defines a webhook subscription endpoint where Deel sends webhooks for the specified events.

Webhook payload

The webhook payload body includes the 'data' field which holds the following fields:

meta
resource
timestamp

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

Field	Description	Example
event_type	Type/name of webhook event.	`contract.created`
logging_id	Unique log id of the event. This can be useful when request support from Deel team.	`Zr8xxEsusAfUxJ4DHndr8`
organization_id	Id of Deel organization.	`12345`

resource
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
Timestamp of webhook.

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:

Field	Use
x-deel-signature	Learn more.
x-deel-hmac-label	HMAC signing key label. If you have multiple subscriptions, you can use the level to identify the signing key signatures.
x-deel-webhook-version	Specifies what version of the Deel API was used to serialize the webhook event payload.