Simulations

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:

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

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

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

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:

1 {
2   "data": {
3     "meta": {
4       "event_type": "contract.created",
5       "organization_id": "org_abc123",
6       "event_id": "evt_sim_xyz789",
7       "occurred_at": "2025-02-05T15:39:38.070Z",
8       "is_simulation": true  // ← Simulation flag
9     },
10     "resource": [
11       {
12         "contract_id": "ctr_test_123",
13         "worker_email": "test.worker@example.com",
14         "status": "pending",
15         "type": "eor",
16         "country": "US"
17       }
18     ]
19   },
20   "timestamp": "2025-02-05T15:39:38.070Z"
21 }

Handling Simulated Events

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

1 app.post('/webhooks/deel', async (req, res) => {
2   const { meta } = req.body.data;
3   const resource = req.body.data.resource[0];
4 
5   // Check if this is a simulation
6   if (meta.is_simulation) {
7     console.log('📋 Received simulated event:', meta.event_type);
8 
9     // Log but don't process
10     await logSimulatedEvent(meta.event_type, resource);
11 
12     return res.status(200).send('Simulation received');
13   }
14 
15   // Process real events normally
16   await processEvent(meta.event_type, resource);
17 
18   res.status(200).send('OK');
19 });

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:

1 const eventsToTest = [
2   'contract.created',
3   'contract.signed',
4   'payment.completed'
5 ];
6 
7 // Test each one in Developer Center
8 eventsToTest.forEach(event => {
9   console.log(`✓ Test ${event}`);
10 });

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:

1 if (meta.is_simulation) {
2   // Log, validate, test - but don't create real records
3   await validateWebhookStructure(resource);
4   await testBusinessLogic(resource);
5   return;
6 }
7 
8 // Only process real events
9 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:

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

1 // Allow both real and simulated events
2 if (!meta.is_simulation) {
3   // Only validate real events strictly
4   await strictValidation(resource);
5 }

Want to simulate more than 10 times per hour

Options:

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

Local testing:

1 // Create test payload locally
2 const testPayload = {
3   data: {
4     meta: {
5       event_type: 'contract.created',
6       is_simulation: true
7     },
8     resource: [{ /* test data */ }]
9   }
10 };
11 
12 // Test your handler
13 await handleWebhook(testPayload);

Additional Resources

Webhook Events

Explore all available event types

Managing Webhooks

Create and configure webhooks

Overview

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:

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

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

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

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:

1 {
2   "data": {
3     "meta": {
4       "event_type": "contract.created",
5       "organization_id": "org_abc123",
6       "event_id": "evt_sim_xyz789",
7       "occurred_at": "2025-02-05T15:39:38.070Z",
8       "is_simulation": true  // ← Simulation flag
9     },
10     "resource": [
11       {
12         "contract_id": "ctr_test_123",
13         "worker_email": "test.worker@example.com",
14         "status": "pending",
15         "type": "eor",
16         "country": "US"
17       }
18     ]
19   },
20   "timestamp": "2025-02-05T15:39:38.070Z"
21 }

Handling Simulated Events

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

1 app.post('/webhooks/deel', async (req, res) => {
2   const { meta } = req.body.data;
3   const resource = req.body.data.resource[0];
4 
5   // Check if this is a simulation
6   if (meta.is_simulation) {
7     console.log('📋 Received simulated event:', meta.event_type);
8 
9     // Log but don't process
10     await logSimulatedEvent(meta.event_type, resource);
11 
12     return res.status(200).send('Simulation received');
13   }
14 
15   // Process real events normally
16   await processEvent(meta.event_type, resource);
17 
18   res.status(200).send('OK');
19 });

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:

1 const eventsToTest = [
2   'contract.created',
3   'contract.signed',
4   'payment.completed'
5 ];
6 
7 // Test each one in Developer Center
8 eventsToTest.forEach(event => {
9   console.log(`✓ Test ${event}`);
10 });

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:

1 if (meta.is_simulation) {
2   // Log, validate, test - but don't create real records
3   await validateWebhookStructure(resource);
4   await testBusinessLogic(resource);
5   return;
6 }
7 
8 // Only process real events
9 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:

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

1 // Allow both real and simulated events
2 if (!meta.is_simulation) {
3   // Only validate real events strictly
4   await strictValidation(resource);
5 }

Want to simulate more than 10 times per hour

Options:

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

Local testing:

1 // Create test payload locally
2 const testPayload = {
3   data: {
4     meta: {
5       event_type: 'contract.created',
6       is_simulation: true
7     },
8     resource: [{ /* test data */ }]
9   }
10 };
11 
12 // Test your handler
13 await handleWebhook(testPayload);

Additional Resources

Webhook Events

Explore all available event types

Managing Webhooks

Create and configure webhooks

1	{
2	"data": {
3	"meta": {
4	"event_type": "contract.created",
5	"organization_id": "org_abc123",
6	"event_id": "evt_sim_xyz789",
7	"occurred_at": "2025-02-05T15:39:38.070Z",
8	"is_simulation": true // ← Simulation flag
9	},
10	"resource": [
11	{
12	"contract_id": "ctr_test_123",
13	"worker_email": "test.worker@example.com",
14	"status": "pending",
15	"type": "eor",
16	"country": "US"
17	}
18	]
19	},
20	"timestamp": "2025-02-05T15:39:38.070Z"
21	}

1	app.post('/webhooks/deel', async (req, res) => {
2	const { meta } = req.body.data;
3	const resource = req.body.data.resource[0];
4
5	// Check if this is a simulation
6	if (meta.is_simulation) {
7	console.log('📋 Received simulated event:', meta.event_type);
8
9	// Log but don't process
10	await logSimulatedEvent(meta.event_type, resource);
11
12	return res.status(200).send('Simulation received');
13	}
14
15	// Process real events normally
16	await processEvent(meta.event_type, resource);
17
18	res.status(200).send('OK');
19	});

1	const eventsToTest = [
2	'contract.created',
3	'contract.signed',
4	'payment.completed'
5	];
6
7	// Test each one in Developer Center
8	eventsToTest.forEach(event => {
9	console.log(`✓ Test ${event}`);
10	});

1	if (meta.is_simulation) {
2	// Log, validate, test - but don't create real records
3	await validateWebhookStructure(resource);
4	await testBusinessLogic(resource);
5	return;
6	}
7
8	// Only process real events
9	await createDatabaseRecords(resource);

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

1	// Allow both real and simulated events
2	if (!meta.is_simulation) {
3	// Only validate real events strictly
4	await strictValidation(resource);
5	}

1	// Create test payload locally
2	const testPayload = {
3	data: {
4	meta: {
5	event_type: 'contract.created',
6	is_simulation: true
7	},
8	resource: [{ /* test data */ }]
9	}
10	};
11
12	// Test your handler
13	await handleWebhook(testPayload);