Paddle Billing
Search

Simulate webhooks

Use webhook simulator to send test webhooks for single events or predefined scenarios as part of testing and integration.

You can use webhooks to handle provisioning and fulfilment, and to keep your app in sync with Paddle. For example, you can create an account for a customer in your app when a subscription is created in Paddle and limit customer access to your app if they cancel.

Webhook simulator lets you send test webhooks for single events or scenarios, so you can more easily build and test workflows to keep your app in sync with Paddle.

How it works

You can use webhooks to keep your app in sync with Paddle. For example, you can subscribe to subscription.paused to determine when a subscription pauses and take action in your app, like limiting customer access until resumed.

Key subscription lifecycle events typically involve multiple webhooks. For example, when a customer signs up using a checkout, Paddle creates and updates multiple entities throughout the process — a customer, address, and business to hold customer information; a transaction to collect for payment; and finally a subscription when checkout completes.

To make it easier to test and integrate, webhook simulator lets you send single events or predefined groups of events, called scenarios, without going through the steps to make them occur yourself.

Simulation lifecycle

  1. Create a simulation

    You can create and configure a simulation to tell Paddle which event or predefined sequence of events that you want to simulate and where you want to send data to. Once configured, you can run a simulation any time to send simulated data.

  2. Run your simulation

    Once you've created a simulation, you can run it to send the event or events that are part of it. Paddle creates a simulation run entity for the run to hold information about the events simulated.

  3. Work with simulated events

    Paddle sends simulated webhooks for the event or events that are part of the simulation, creating a simulation run event entity for each event sent. You can list events for a simulation run to see which events were simulated and information about responses from the destination server.

Simulations are reusable configurations. Once you've created and configured a simulation, you can run it any time you like as part of your testing workflows.

Create a simulation

  1. Go to Paddle > Developer tools > Simulations.

  2. Click New simulation.

  3. Choose where to send simulated events using the Destination dropdown box. You can create a new notification destination if you don't already have one.

  4. Enter a descriptive name for your simulation. You can customize payloads to send specific data, so a descriptive name helps you to identify this simulation.

  5. Click the Single event or Scenario tab, then choose the simulated data you want to receive.

  6. Click Create when you're done.

Illustration showing the new simulation drawer in the dashboard. There are fields for destination and name, followed by a toggle for single event or scenario.

Only destinations with the traffic source simulation or all are shown in the list of destinations. platform destinations can only receive traffic for real events to avoid sending simulated data to production endpoints.

Run a simulation

  1. Go to Paddle > Developer tools > Simulations.

  2. Find your simulation in the list, then click the ... action menu and choose View. If you haven't already created a simulation, create one instead.

  3. Click Run simulation to run your simulation. If you've already run your simulation before, click Replay to run it again.

  4. Use the Payload, Request, and Response tabs to work with simulated events.

Illustration showing the event simulation page in the dashboard. It shows a simulation with no runs. There is a button that says run simulation.

You can verify signatures for your simulation to check that events are genuinely sent by Paddle. Click View more to reveal your webhook secret key.

Customize a simulation payload

You can customize the payload for a single event simulation to send specific data as part of your request. Paddle saves your simulated data, so you can use it in the future.

You can only customize payloads for single event simulations. You can't customize payloads for scenarios right now.

  1. Go to Paddle > Developer tools > Simulations.

  2. Find your simulation in the list, then click the ... action menu and choose View. If you haven't already created a simulation, create one instead.

  3. If you haven't run your simulation before, run it.

  4. Click the Payload tab in the preview pane, then click the payload to start editing.

  5. Click Replay to run your simulation with the customized payload.

Illustration showing the event simulation page in the dashboard. There is an address payload, with the line status:archived highlighted to indicate that it's being edited.

Paddle checks the data you enter is valid JSON and that values for fields are the correct type. However, you may still enter incorrect data, like passing transaction totals that don't add up correctly.

Work with simulated events

Paddle creates a simulation run event for the event or events that are part of a simulation.

  1. Go to Paddle > Developer tools > Simulations.

  2. Find your simulation in the list, then click the ... action menu and choose View. If you haven't already created a simulation, create one instead.

  3. If you haven't run your simulation before, run it.

  4. Inspect the Payload, Request, and Response using the tabs in the preview pane. If you're working with a scenario, click the events on the left to see information about a single event sent as part of this scenario.

Illustration showing the simulation page in the dashboard. It shows a scenario, with tabs on the left meant to represent simulated events and an address payload on the right.

Related pages