> 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/simulations/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.deel.wtf/_mcp/server.

# Simulations

> Test your webhook integration safely without affecting production data

## Overview

Webhook simulation allows you to test your integration without triggering real business processes or affecting production data. Simulated events work exactly like production webhooks but are clearly marked so you can handle them differently.

* **Safe Testing:** Test without affecting real data
* **Production-Like:** Uses same infrastructure as real events
* **Easy Debugging:** Validate configuration before going live

## Why Simulate Webhooks?

#### Validate Configuration

Ensure your webhook endpoint is configured correctly:

* URL is accessible
* Signature verification works
* Response time is acceptable
* Error handling is robust

#### Test Integration Logic

Verify your application handles events correctly:

* Events are parsed properly
* Business logic executes as expected
* Database updates work correctly
* No side effects in production systems

#### Debug Issues

Troubleshoot problems safely:

* Reproduce error conditions
* Test edge cases
* Verify fixes without risk
* Check logs and monitoring

#### Train Your Team

Help developers understand the integration:

* See real webhook payloads
* Learn event structures
* Practice responding to events
* Build confidence before production

## How Simulation Works

When you simulate a webhook event:

1. **Deel sends a test payload** to your configured endpoint
2. **The payload is marked** with `"is_simulation": true`
3. **Same authentication and retry logic** applies as production
4. **Event is logged** in webhook delivery history
5. **Your endpoint receives** a realistic test event

> **Info**
>
> Simulated events use the same infrastructure as production webhooks, so they're an accurate test of your integration's reliability.

## Simulating Events in Developer Center

#### Navigate to Developer Center

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

#### Select your webhook

Click on the webhook subscription you want to test

#### View subscribed events

In the webhook details page, you'll see all events you're subscribed to

#### Expand event type

Expand the event type you want to simulate

#### Click Simulate

Click the **Simulate** button next to the event. A dialog appears confirming the simulation was successful.

#### Verify delivery

Check your endpoint logs to confirm the webhook was received

> **Tip**
>
> **Quick testing tip:** Keep the Developer Center open while testing your local endpoint with ngrok. You can simulate events instantly and see results in real-time.

## Simulated Event Payload

Simulated webhooks include the `is_simulation` flag in the payload:

```json
{
  "data": {
    "meta": {
      "event_type": "contract.created",
      "organization_id": "org_abc123",
      "event_id": "evt_sim_xyz789",
      "occurred_at": "2025-02-05T15:39:38.070Z",
      "is_simulation": true  // ← Simulation flag
    },
    "resource": [
      {
        "contract_id": "ctr_test_123",
        "worker_email": "test.worker@example.com",
        "status": "pending",
        "type": "eor",
        "country": "US"
      }
    ]
  },
  "timestamp": "2025-02-05T15:39:38.070Z"
}
```

## Handling Simulated Events

You can detect and handle simulated events differently in your code:

**`Node.js`**

```javascript Node.js
app.post('/webhooks/deel', async (req, res) => {
  const { meta } = req.body.data;
  const resource = req.body.data.resource[0];

  // Check if this is a simulation
  if (meta.is_simulation) {
    console.log('📋 Received simulated event:', meta.event_type);

    // Log but don't process
    await logSimulatedEvent(meta.event_type, resource);

    return res.status(200).send('Simulation received');
  }

  // Process real events normally
  await processEvent(meta.event_type, resource);

  res.status(200).send('OK');
});
```

**`Python`**

```python Python
@app.route('/webhooks/deel', methods=['POST'])
def handle_webhook():
    meta = request.json['data']['meta']
    resource = request.json['data']['resource'][0]

    # Check if this is a simulation
    if meta.get('is_simulation'):
        print(f'📋 Received simulated event: {meta["event_type"]}')

        # Log but don't process
        log_simulated_event(meta['event_type'], resource)

        return jsonify({'status': 'Simulation received'}), 200

    # Process real events normally
    process_event(meta['event_type'], resource)

    return jsonify({'status': 'success'}), 200
```

> **Warning**
>
> **Important:** Always check the `is_simulation` flag to avoid processing test data as if it were real. This prevents duplicate records, incorrect metrics, and unintended side effects.

## Best Practices

#### Test all subscribed events

Simulate each event type you're subscribed to:

```javascript
const eventsToTest = [
  'contract.created',
  'contract.signed',
  'payment.completed'
];

// Test each one in Developer Center
eventsToTest.forEach(event => {
  console.log(`✓ Test ${event}`);
});
```

#### Check logs after each simulation

Always verify:

* Event was received
* Status code is correct
* Response time is acceptable
* No errors in your application logs

#### Test with production-like data

Use realistic test data that mirrors your production use cases:

* Actual country codes
* Valid email formats
* Realistic contract amounts
* Expected date formats

#### Simulate edge cases

Test unusual scenarios:

* Very long field values
* Special characters in names
* Multiple resources in array
* Missing optional fields

#### Use simulation flag properly

Don't process simulated events as real data:

```javascript
if (meta.is_simulation) {
  // Log, validate, test - but don't create real records
  await validateWebhookStructure(resource);
  await testBusinessLogic(resource);
  return;
}

// Only process real events
await createDatabaseRecords(resource);
```

## Troubleshooting Simulations

#### Simulation not arriving

**Check:**

* Is your endpoint accessible?
* Is the webhook enabled?
* Did you hit the rate limit (10/hour)?
* Is your server responding to requests?

**Test connectivity:**

```bash
curl -X POST https://your-endpoint.com/webhooks/deel \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'
```

#### Simulation failing but production works

**Possible causes:**

* Your code rejects simulated events
* Different validation for test data
* Sandbox vs production environment mismatch

**Solution:**
Ensure simulated events can pass through your validation:

```javascript
// Allow both real and simulated events
if (!meta.is_simulation) {
  // Only validate real events strictly
  await strictValidation(resource);
}
```

#### Want to simulate more than 10 times per hour

**Options:**

1. Create additional webhook subscriptions for testing
2. Use webhook logs to replay past events
3. Retrieve sample payloads from API and test locally
4. Use the event structure documentation to build test payloads

**Local testing:**

```javascript
// Create test payload locally
const testPayload = {
  data: {
    meta: {
      event_type: 'contract.created',
      is_simulation: true
    },
    resource: [{ /* test data */ }]
  }
};

// Test your handler
await handleWebhook(testPayload);
```

## Additional Resources

#### [Webhook Events](/api/webhooks/events)

Explore all available event types

#### [Managing Webhooks](/api/webhooks/no-code)

Create and configure webhooks

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