> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.deel.wtf/api/stable/webhooks/events/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.deel.wtf/_mcp/server.

# Events

> Explore available webhook events and their payloads

## Overview

Deel provides a comprehensive set of webhook events across all services. Each event represents a specific action or state change in your Deel account, allowing you to build real-time integrations.

* **100+ Events:** Events for contracts, payments, workers, and more
* **Detailed Payloads:** Each event includes relevant resource data
* **Easy Discovery:** Browse events via API or Developer Center

## Discovering Available Events

There are two ways to explore all available webhook events:

### Via API

Use the webhook events endpoint to retrieve the complete list programmatically:

**`cURL`**

```bash cURL
curl 'https://api.letsdeel.com/rest/webhooks/events/types' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

**`Node.js`**

```javascript Node.js
const axios = require('axios');

async function listWebhookEvents() {
  const response = await axios.get(
    'https://api.letsdeel.com/rest/webhooks/events/types',
    {
      headers: {
        'Authorization': `Bearer ${process.env.DEEL_API_TOKEN}`
      }
    }
  );

  console.log('Available events:', response.data);

  // Filter by category
  const contractEvents = response.data.filter(
    event => event.name.startsWith('contract.')
  );

  return response.data;
}

listWebhookEvents();
```

**`Python`**

```python Python
import requests
import os

def list_webhook_events():
    response = requests.get(
        'https://api.letsdeel.com/rest/webhooks/events/types',
        headers={
            'Authorization': f'Bearer {os.getenv("DEEL_API_TOKEN")}'
        }
    )

    events = response.json()
    print(f'Available events: {events}')

    # Filter by category
    contract_events = [
        event for event in events
        if event['name'].startswith('contract.')
    ]

    return events

list_webhook_events()
```

**Response format:**

```json
{
  "data": [
    {
      "id": "7459da2b-9caf-4b51-bd84-251ce2bec485",
      "module_name": "payslips",
      "module_label": "Payslips",
      "name": "eor.payslips.available",
      "description": "Triggered when EOR payslips are available",
      "payload_example": {...},
      "created_at": "2023-11-10T11:08:20.194Z",
      "updated_at": "2025-02-07T11:47:35.635Z"
    }
  ]
}
```

### Via Developer center

For a visual experience, use the Deel Developer Center:

#### Navigate to Developer Center

Log in to [app.deel.com](https://app.deel.com) and go to **Settings** → **Developer Center**

#### Go to Webhooks tab

Click on the **Webhooks** tab

#### View available events

When creating or editing a webhook, you'll see a searchable list of all available events with:

* Event name
* Description
* Category
* Example payload

#### Preview event payloads

Click on any event to see its complete payload structure and example data

> **Tip**
>
> **Pro tip:** The Developer Center lets you search and filter events by category, making it easy to find exactly what you need.

## Event Payload Structure

All webhook events follow a consistent structure:

```json
{
  "data": {
    "meta": {
      "event_type": "contract.created",
      "organization_id": "org_abc123",
      "event_id": "evt_xyz789",
      "occurred_at": "2025-02-05T15:39:38.070Z"
    },
    "resource": [
      {
        // Event-specific data
        "contract_id": "ctr_123456",
        "worker_email": "worker@example.com",
        "status": "pending",
        "type": "eor",
        "country": "US"
        // ... more fields specific to the event
      }
    ]
  },
  "timestamp": "2025-02-05T15:39:38.070Z"
}
```

### Payload components

#### meta - Event metadata

Contains metadata about the event:

* `event_type`: The event that occurred
* `organization_id`: Your organization ID
* `event_id`: Unique identifier for this event
* `occurred_at`: When the event happened

#### resource - Event data

Contains the resource that changed:

* Structure varies by event type
* Always includes IDs for lookups
* May contain nested objects
* Includes all relevant resource fields

#### timestamp - Delivery time

When the webhook was sent:

* ISO 8601 formatted timestamp
* When webhook was delivered (not when event occurred)
* Use for logging and debugging
* May differ slightly from `occurred_at`

#### headers - HTTP headers

Important HTTP headers included with every webhook:

* `x-deel-signature`: HMAC-SHA256 signature to verify authenticity
* `x-deel-webhook-version`: API version used for serialization
* `x-deel-hmac-label`: Identifies which signing key was used

## Viewing Event Payloads

### In Developer center

The Developer Center provides a visual way to explore event payloads:

#### Open webhook details

Navigate to a webhook in the Developer Center

#### Click 'View Events'

Browse the list of available events for your webhook

#### Select an event

Click on any event to see:

* Full payload structure
* Field descriptions
* Example values
* Data types

#### Copy for testing

Use the example payload to test your integration

### Via API response

When you retrieve events from the API, each event includes a `payload_example` field showing the exact structure you'll receive:

**`Node.js`**

```javascript Node.js
const axios = require('axios');

async function getEventPayload() {
  const response = await axios.get(
    'https://api.letsdeel.com/rest/webhooks/events/types',
    {
      headers: {
        'Authorization': `Bearer ${process.env.DEEL_API_TOKEN}`
      }
    }
  );

  // Access the payload_example for any event
  const events = response.data.data;
  const contractCreatedEvent = events.find(
    event => event.name === 'contract.created'
  );

  console.log('Event payload structure:', contractCreatedEvent.payload_example);
}
```

**`Python`**

```python Python
import requests
import os

def get_event_payload():
    response = requests.get(
        'https://api.letsdeel.com/rest/webhooks/events/types',
        headers={
            'Authorization': f'Bearer {os.getenv("DEEL_API_TOKEN")}'
        }
    )

    events = response.json()['data']

    # Access the payload_example for any event
    contract_created = next(
        (e for e in events if e['name'] == 'contract.created'),
        None
    )

    if contract_created:
        print('Event payload structure:', contract_created['payload_example'])
```

The `payload_example` field contains the complete webhook structure including `meta`, `resource`, and `timestamp` fields, allowing you to understand exactly what data you'll receive when subscribing to that event.

## Filtering Events

When creating a webhook subscription, you can filter which events you receive:

### Subscribe to specific events

```javascript
// Subscribe only to contract events
const webhook = await createWebhook({
  url: 'https://yourapp.com/webhooks/deel',
  events: [
    'contract.created',
    'contract.signed',
    'contract.terminated'
  ]
});
```

## Next Steps

#### [Webhook Simulation](/api/webhooks/simulations)

Test your integration safely

> Build apps and integrations that extend and enhance the Deel services.