> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Webhook simulator

Understand how webhook simulator works and how simulations are created, configured, and run.

---

Webhook simulator lets you send test webhooks to your endpoint without triggering real transactions. Use it to build and test your [webhook integrations](https://developer.paddle.com/webhooks/how-webhooks-work.md) without going through the steps to trigger events in a real flow.

{% card-group cols=3 %}
{% card title="Test safely" icon="carbon:test-tool" %}
Send webhooks without affecting real data. Works in sandbox and production.
{% /card %}

{% card title="Simulate full flows" icon="carbon:flow" %}
Trigger a sequence of related events, like all webhooks for subscription creation.
{% /card %}

{% card title="Real and reusable" icon="carbon:recycle" %}
Create reusable simulations, then run them anytime with real payloads.
{% /card %}
{% /card-group %}

## Billing scenarios involve multiple webhooks

Key subscription lifecycle events typically involve multiple webhooks. For example, when a customer signs up using checkout, Paddle:

- Creates and updates a [customer](https://developer.paddle.com/api-reference/customers/overview.md), [address](https://developer.paddle.com/api-reference/addresses/overview.md), and [business](https://developer.paddle.com/api-reference/businesses/overview.md) to hold customer information.
- Creates and updates a [transaction](https://developer.paddle.com/api-reference/transactions/overview.md) to collect payment.
- Creates a [subscription](https://developer.paddle.com/api-reference/subscriptions/overview.md) when checkout completes.

Each step of the process fires its own webhook. Webhook simulator lets you send single events or predefined groups of events, called scenarios, without going through the steps to make them occur yourself.

## Single events vs. scenarios

A **simulation** is a reusable configuration of events that you want to test. There are two kinds of simulations:

- **Single events** simulate one webhook event. You can [customize the payload](https://developer.paddle.com/webhooks/simulator/test-webhooks#customize-simulation-data.md) after running to send specific data.
- **Scenarios** simulate a predefined sequence of events for a lifecycle flow, like a subscription creation or renewal. You can [configure scenarios](https://developer.paddle.com/webhooks/simulator/test-webhooks#configure-simulation.md) to populate payloads with real entities and test different flows.

## Configuration

You can configure scenarios to match your real flows and test different scenarios. When configuring, you can include:

- **Entities**  
  Populate simulated webhook payloads with your real data. They map to your existing Paddle entities, like [customers](https://developer.paddle.com/api-reference/customers/overview.md) and [subscriptions](https://developer.paddle.com/api-reference/subscriptions/overview.md).
- **Options**  
  Control what flow occurs in the scenario, including which webhooks are sent and the details they contain. Options relate to user actions or entity field values at the time the scenario takes place.

For example, you can:

- Provide a customer ID to populate simulated events with that customer's details.
- Set a payment outcome of `failed` to simulate a subscription renewal where payment doesn't go through.

{% callout type="info" %}
Providing entities only populates payload data. For example, providing a customer ID doesn't change which webhooks are sent. To change which webhooks are sent during a simulated flow, use options.
{% /callout %}

## Simulation lifecycle

Once you've created and configured a simulation, you can run it as many times as you want as part of your testing workflows.

```mermaid
flowchart LR
    A[Create simulation] --> B["Configure\n(scenarios only, optional)"]
    B --> C[Run simulation]
    C --> D[Work with events]
    D -->|Run again| C
```

1. **Create a simulation**  
  Tell Paddle which event or predefined sequence to simulate, and which notification destination to send events to.
2. **Configure a simulation**  
  For scenario simulations, optionally populate payloads with your real Paddle entities and choose which flow to simulate.
3. **Run your simulation**  
  Trigger the event or events. Paddle creates a [simulation run entity](https://developer.paddle.com/api-reference/simulation-runs/overview.md) for each run.
4. **Work with simulated events**  
  Inspect each event's payload, request, and your server's response. Paddle creates a [simulation run event entity](https://developer.paddle.com/api-reference/simulation-events/overview.md) for each event sent.