Debug webhooks and callbacks

A payment provider or Git host sends webhooks you can’t easily inspect, and reproducing one means waiting for a real event. This guide receives webhook deliveries on a local port with the API client’s Webhooks view, shows what each one contained, answers with a response you choose, and forwards or replays them to your dev server so you can debug the handler as many times as you need.

What you need

The API client (<kbd>⇧</kbd> <kbd>⌘</kbd> <kbd>O</kbd>)	The Webhooks view lives here
A way to reach the port from the sender, for internet webhooks	A tunnel such as cloudflared or ngrok
Your dev server’s URL, if you want deliveries forwarded to it	For example http://localhost:3000/webhooks

Start the receiver

1. In the API Client, open the Webhooks section.

   12345

   The Webhooks receiver: pick a port, a canned response, and an optional forward target.

   1. Webhooks section
   2. Port to listen on
   3. Status and body to answer with
   4. Forward to (optional)
   5. Start Listening

   ×

   

2. Set the Port (9999 by default), the Respond with status and body the sender receives, and optionally a Forward to URL (your dev server).

3. Click Start Listening. The view shows http://localhost:PORT, ready to receive.

Note

The receiver listens on localhost. To receive from the internet, expose the port with a tunnel such as cloudflared or ngrok, and give the sender the tunnel’s public URL.

Point the sender at it

1. In the provider’s dashboard, set the webhook URL to your local URL (or the tunnel URL for internet deliveries).

2. Trigger an event, or use the provider’s “send test” button.

Inspect each delivery

Deliveries appear in the list as they arrive.

1. Select a delivery to see its method, path, headers and body. The body uses the same viewers as the rest of the app (JSON tree, pretty, raw).

2. The sender gets the response you set under Respond with, so it marks the delivery as accepted. If you set a Forward to URL, each delivery is also sent there; the row shows the forward status (or that it failed).

Forward and replay to your dev server

The point of the receiver is that you can debug the handler repeatedly without waiting for new events.

Replay a delivery

Select a delivery, enter your dev server URL in Replay to URL, and click Replay. The exact delivery is sent again, so you can fix the handler and re-run the same payload until it works.

Open as a request

Click Open as Request to turn the delivery into a saved request in the API client (method, headers and JSON body prefilled). From there you can edit it, send it, add tests, and save it in a collection.

Tip

Forwarding (set once in Forward to) relays every delivery live; replaying resends one delivery on demand. Use forwarding to mirror real events to your dev server, and replay to iterate on a single tricky payload.

Trigger a Flow on a webhook

To run a chain of requests when a delivery arrives — verify a signature, then call your API, then check the result — attach the webhook to a Flow.

1. Build a Flow in the Flows section (blocks run top to bottom; expressions are JavaScript).

2. In the Flow’s Automation section, turn on Run when a webhook arrives at and note the path (for example /flows/create-and-fetch-a-pet).

   123

   A Flow's Automation: run it when a webhook arrives at a path.

   1. Flows section
   2. Run when a webhook arrives at this path
   3. Notify me when an automatic run fails

   ×

   

3. Start the webhook receiver. A delivery to that path runs the Flow, and the delivery is available inside it as the trigger variable (trigger.body, trigger.headers).

Clean up

1. Click Stop in the Webhooks view to stop listening.

2. Remove or disable the webhook in the provider’s dashboard, and shut down the tunnel if you started one.

3. Turn off the Flow’s webhook automation if you no longer want it to run.

Related

Monitors and webhooksThe receiver, forwarding and replay in full.

FlowsChained requests with logic, triggered on a schedule or a webhook.

Collections and requestsSave a delivery as a request and build on it.

Capture to clientTurn captured traffic into saved requests.