> This page is for API, version 2026-01-01 (Stable) (default).
> For other versions, use one of these documentation indexes:
> - 2026-01-01 (Stable) (default): https://developer.deel.com/api/stable/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_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'
```

**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:

**`cURL`**

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

Find the event you're interested in (for example, `contract.created`) in the response array and inspect its `payload_example` field. The 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

**`cURL`**

```bash cURL
curl -X POST 'https://api.letsdeel.com/rest/webhooks' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Contract events",
    "description": "Subscribe only to contract events",
    "status": "enabled",
    "url": "https://yourapp.com/webhooks/deel",
    "api_version": "v2",
    "events": ["contract.created", "contract.signed", "contract.terminated"]
  }'
```

## Next Steps

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

Test your integration safely