Introduction

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

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

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

• Applications requiring immediate notification when an event occurs
• Reducing unnecessary API requests and server load
• Event-driven architectures that can process asynchronous HTTP callbacks

• Server pushes event data to your endpoint when triggered
• Near real-time delivery with minimal delay
• More efficient for infrequent or unpredictable updates
• Endpoint setup and secure handling required

• One-time or scheduled initial data sync to align systems before using webhooks
• Backup solution when webhook delivery is not possible due to technical limitations
• Legacy systems unable to receive incoming HTTP requests
• Critical scenarios where you need redundancy in event delivery

• Client periodically checks the API for new data at scheduled intervals
• Events are not detected in real time—there is inherent delay based on the polling interval
• Increased server load and API usage compared to webhooks
• Simpler infrastructure—public endpoints are not required

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
});

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);

Only subscribe to events your application needs.

Why? Reduces unnecessary traffic and processing. You can always add more events later.

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
});