***

title: Events
description: 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:

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

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

  async function listWebhookEvents() {
    const response = await axios.get(
      'https://api.letsdeel.com/rest/v2/webhooks/events',
      {
        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
  import requests
  import os

  def list_webhook_events():
      response = requests.get(
          'https://api.letsdeel.com/rest/v2/webhooks/events',
          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()
  ```
</CodeGroup>

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

<Steps>
  <Step title="Navigate to Developer Center">
    Log in to [app.deel.com](https://app.deel.com) and go to **Settings** → **Developer Center**
  </Step>

  <Step title="Go to Webhooks tab">
    Click on the **Webhooks** tab
  </Step>

  <Step title="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
  </Step>

  <Step title="Preview event payloads">
    Click on any event to see its complete payload structure and example data
  </Step>
</Steps>

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

## 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

<AccordionGroup>
  <Accordion title="meta - Event metadata" icon="tag">
    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
  </Accordion>

  <Accordion title="resource - Event data" icon="database">
    Contains the resource that changed:

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

  <Accordion title="timestamp - Delivery time" icon="clock">
    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`
  </Accordion>

  <Accordion title="headers - HTTP headers" icon="list">
    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
  </Accordion>
</AccordionGroup>

## Viewing Event Payloads

### In Developer Center

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

<Steps>
  <Step title="Open webhook details">
    Navigate to a webhook in the Developer Center
  </Step>

  <Step title="Click 'View Events'">
    Browse the list of available events for your webhook
  </Step>

  <Step title="Select an event">
    Click on any event to see:

    * Full payload structure
    * Field descriptions
    * Example values
    * Data types
  </Step>

  <Step title="Copy for testing">
    Use the example payload to test your integration
  </Step>
</Steps>

### Via API Response

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

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

  async function getEventPayload() {
    const response = await axios.get(
      'https://api.letsdeel.com/rest/v2/webhooks/events',
      {
        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
  import requests
  import os

  def get_event_payload():
      response = requests.get(
          'https://api.letsdeel.com/rest/v2/webhooks/events',
          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'])
  ```
</CodeGroup>

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

<CardGroup cols={1}>
  <Card title="Webhook Simulation" icon="fa-light vial" href="/api/webhooks/simulations">
    Test your integration safely
  </Card>
</CardGroup>