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

# Configure your webhook scenario simulations

Get deeper control when testing your integration flows by configuring webhook simulator scenarios. Use your own data in webhooks, and customize flows by providing specific options to more accurately test your integrations end-to-end.

---

## What's new?

We've released an update to [webhook simulator](https://developer.paddle.com/webhooks/test-webhooks.md) for scenario simulations. You can now:

- Populate simulated webhook payloads with real data [by providing entities](#entities-change-details)
- Test a greater variety of common flows for each scenario [by selecting from a range of granular options](#options-change-details)

This lets you more accurately test and optimize your webhook integrations to have increased confidence everything is working as expected before going live.

## How it works

You can use [webhook simulator](https://developer.paddle.com/webhooks/test-webhooks.md) to send test webhooks for single events or predefined scenarios as part of testing and integration.

Previously, scenarios played a predefined set of events. Now, you can configure your scenario webhook simulations with [entities](#entities-change-details) and [options](#options-change-details).

Every scenario can be configured with entities and options. Each scenario has its own [set list of entities and options you can provide](https://developer.paddle.com/webhooks/test-webhooks#simulation-configuration.md).

### Entities

Use entities to populate simulated webhook payloads with your real data.

They map to your existing Paddle entities, such as [customers](https://developer.paddle.com/api-reference/customers/overview.md) and [subscriptions](https://developer.paddle.com/api-reference/subscriptions/overview.md).

Providing existing entities when configuring a scenario simulation populates the payloads of sent webhooks with the details of that entity, but **doesn't** determine what webhooks are sent in a flow.

{% api-example method="POST" path="/simulations" %}

```json {% title="Request" %}
{
  "notification_setting_id": "ntfset_01j82d983j814ypzx7m1fw2jpz",
  "name": "Create a subscription creation simulation with config",
  "type": "subscription_creation",
  "config": {
    "subscription_creation": {
      "entities": {
        "customer_id": "ctm_01grnn4zta5a1mf02jjze7y2ys",
        "address_id": "add_01gm302t81w94gyjpjpqypkzkf",
        "business_id": "biz_01grrebrzaee2qj2fqqhmcyzaj",
        "payment_method_id": "paymtd_01hkm9xwqpbbpr1ksmvg3sx3v1",
        "discount_id": "dsc_01gv5kpg05xp104ek2fmgjwttf",
        "items": [
          {
            "price_id": "pri_01gsz8z1q1n00f12qt82y31smh",
            "quantity": 5
          }
        ]
      }
    }
  }
}
```

{% /api-example %}

### Options

Options determine what flow should occur within specific scenarios, including which webhooks are sent and the details they contain.

These are related to what user actions were taken, or what fields are present on certain entities when the scenario takes place.

For example, you can specify whether a user failed a payment when renewing their subscription, and if that subscription should cancel or pause.

{% api-example method="POST" path="/simulations" %}

```json {% title="Request" %}
{
  "notification_setting_id": "ntfset_01j82d983j814ypzx7m1fw2jpz",
  "name": "Create a failed subscription renewal simulation with subscription ID",
  "type": "subscription_renewal",
  "config": {
    "subscription_renewal": {
      "entities": {
        "subscription_id": "sub_01h04vsc0qhwtsbsxh3422wjs4"
      },
      "options": {
        "payment_outcome": "failed",
        "dunning_exhausted_action": "cancel"
      }
    }
  }
}
```

{% /api-example %}

## Next steps

This change is available in version `1` of the Paddle API, and in the [Paddle dashboard](https://sandbox-vendors.paddle.com/simulations-v2).

It's a non-breaking change, meaning it doesn't impact existing integrations.

We recommend reading more on [how to configure simulations](https://developer.paddle.com/webhooks/test-webhooks#configure-simulation.md), which [entities and options](https://developer.paddle.com/webhooks/test-webhooks#simulation-configuration.md) are available for each scenario type, and which webhooks are sent based on which configuration options have been selected.

- [Subscription created scenario](https://developer.paddle.com/webhooks/scenarios/subscription-created.md)
- [Subscription renewed scenario](https://developer.paddle.com/webhooks/scenarios/subscription-renewed.md)
- [Subscription paused scenario](https://developer.paddle.com/webhooks/scenarios/subscription-paused.md)
- [Subscription resumed scenario](https://developer.paddle.com/webhooks/scenarios/subscription-resumed.md)
- [Subscription canceled scenario](https://developer.paddle.com/webhooks/scenarios/subscription-canceled.md)
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| `config` | Field | added | Simulation | Entities and options for configuring scenario simulations. |