Introduction | Deel | Documentation

Overview

Deel Webhooks deliver real-time notifications for key platform events, allowing you to build efficient and responsive integrations without relying on constant polling.

Real-time Updates: Receive notifications as events occur
Secure Delivery: Every payload is signed using SHA256
Flexible Subscriptions: Manage webhook subscriptions via API or Developer Center

Use Cases

Here are a few examples of how you might use webhooks:

Syncing Data

Automatically update your system when new contracts are created or modified in Deel.

Real-time Notifications

Trigger alerts or workflows in your internal tools when important events happen.

Workflow Automation

Start external processes based on specific events like contract signatures or payment completions.

Webhooks vs Polling

Understanding when to use webhooks versus polling helps you build more efficient integrations.

When to Use Polling

Use polling if:

Updates are frequent
You don’t need updates in real-time

Characteristics:

Resource-intensive
Predictable load
Simpler to implement

When to Use Webhooks

Use webhooks if:

Updates are infrequent
You need updates in real-time

Characteristics:

Efficient, event-triggered
Lower API usage
Requires endpoint setup

Comparison

Method	When to Use	Characteristics
Polling	Frequent updates, non-real-time	Resource-intensive, predictable
Webhooks	Infrequent updates, real-time needed	Efficient, event-triggered

How Webhooks Work

When an event occurs in your Deel account, Deel sends an HTTP POST request to your configured endpoint with details about what happened.

Webhook Structure

Each webhook request contains:

Headers

Payload

Security

Every webhook includes these HTTP headers:

Header	Purpose
`x-deel-signature`	HMAC-SHA256 signature for verifying payload authenticity
`x-deel-hmac-label`	Identifies which signing key was used
`x-deel-webhook-version`	API version used for serialization

Available Events

Deel supports a wide range of webhook events across different services.

Get the complete list: Use the GET /webhooks/events API endpoint to retrieve all available event types and their descriptions.

Webhook Reliability

Deel ensures webhook delivery through an automatic retry mechanism:

Retry Behavior

If your endpoint fails to respond with a 2xx status code, Deel will retry delivery:

Attempt	Delay	Status
1st retry	1 minute	Active
2nd retry	2 minutes	Active
3rd retry	4 minutes	Active
4th retry	8 minutes	Active
5th retry	16 minutes	Active
6th retry	32 minutes	Active
7th retry	1 hour	Active
8th retry	2 hours	Active
9th retry	4 hours	Active
10th attempt	16 hours	Webhook disabled if fails

After 10 consecutive failures, the webhook subscription is automatically disabled. You’ll need to re-enable it manually through the API or Developer Center.

What Counts as a Failure?

Non-2xx HTTP status code (400, 401, 403, 500, etc.)
Connection timeout (endpoint doesn’t respond within 30 seconds)
Network errors or unreachable endpoint

Best Practices

Respond quickly

Return a 200 OK response within 30 seconds (ideally under 5 seconds).

Why? Prevents timeouts and retry storms. Process webhooks asynchronously if needed:

1 app.post('/webhooks', async (req, res) => {
2   // Immediately acknowledge
3   res.status(200).send('OK');
4 
5   // Process asynchronously
6   await queue.add('process-webhook', req.body);
7 });

Handle duplicate events

Webhooks may be delivered more than once due to network issues or retries.

Solution: Make your handlers idempotent by tracking processed event IDs:

1 const eventId = webhook.data.meta.event_id;
2 
3 if (await db.isProcessed(eventId)) {
4   return; // Already processed
5 }
6 
7 await processEvent(webhook);
8 await db.markProcessed(eventId);

Implement reconciliation

Don’t rely solely on webhooks. Run periodic reconciliation jobs to catch any missed events:

1 // Daily sync to catch any gaps
2 cron.schedule('0 0 * * *', async () => {
3   const lastSync = await getLastSyncTime();
4   const updates = await deelAPI.get('/contracts', {
5     params: { updated_after: lastSync }
6   });
7   await reconcileData(updates);
8 });

Get Started

Ready to set up webhooks? Choose your path:

Webhooks Quickstart

Programmatic setup with code examples in multiple languages

No Code

Set up webhooks using the visual Developer Center interface