Docs / Capturing traffic

Webhook inboxes

A URL that catches webhooks and turns them into a diagram.

A webhook inbox is an address you give to a service that sends webhooks, such as Stripe, GitHub or Shopify. Every delivery it sends is captured with its headers and body, so you can see exactly what arrives, and you can turn the deliveries you pick into a sequence diagram with one click.

#Create an inbox

1. Sign in, then open Webhooks in the sidebar, under Capture.
2. Name the inbox after the service that will send to it, such as Stripe, and click Create inbox.
3. Copy the address. It looks like https://volley.sh/hook/ followed by 24 letters and digits.

To make more inboxes, use New inbox. Each inbox has its own tab with a count of what it holds.

#Point a service at it

Paste the address wherever the service asks for a webhook or endpoint URL. The inbox page has a Where do I paste it? section with pointers for common senders:

• Stripe: Developers, then Webhooks, then Add endpoint. For local testing you can also forward events with stripe listen --forward-to <address>.
• GitHub: a repository's or organisation's Settings, then Webhooks. Set the content type to application/json.
• Shopify: the store's notification settings, or the Admin API.
• Anything else: any method and any path under the address is captured, so https://volley.sh/hook/<token>/orders/created?debug=1 works too.

Click Send a test request to check the inbox before the real sender is set up.

#What the inbox shows

The page refreshes every few seconds while it is open. Each delivery is listed with its method, the event name (or the path when there is none) and the time. Click one to preview its body and headers. Older deliveries load 50 at a time with Show older requests.

The inbox answers each captured delivery with 200 and {"ok": true}, so senders see a success and do not retry.

#Draw a diagram

Select the deliveries you want, or none to take everything that is loaded, and click the Diagram button. Its label says what it will use: Diagram it, Diagram all, Diagram N shown or Diagram N. The editor opens with:

• a lane for the sender, named from its user agent when Volley recognises it (Stripe, GitHub, Shopify, Slack, Twilio, SendGrid, Mailgun, Postmark, GitLab, Bitbucket, Linear, Square, PayPal, Svix and Zapier), or after the inbox otherwise;
• a lane called Your app;
• one arrow per delivery in the order they arrived, labelled with the path and the event type, such as POST /webhook (checkout.session.completed);
• the body as the arrow's in: payload, with secrets redacted, and a 200 OK reply.

The event type is read from headers such as X-GitHub-Event and X-Shopify-Topic, or from fields such as type, event or topic in the body. Headers are not included in the diagram.

From there, rename Your app to your service, add the calls your handler makes, and save.

#Privacy

• Authorization, Proxy-Authorization, Cookie, X-Api-Key and X-Auth-Token headers are redacted when a delivery is stored. Network headers added along the way, such as forwarding and tracing headers, are dropped.
• Bodies are stored as they arrived, so you can see exactly what was sent. Secrets in bodies are redacted when you draw the diagram, not before. Signature headers such as Stripe-Signature are kept.
• Bodies over 64 KB are cut at 64 KB, and binary bodies are recorded by size only.
• Only you can see your inboxes.

Use test-mode or sandbox events where you can.

#Clear and delete

Open the three-dot menu on an inbox:

• Clear requests deletes every captured delivery.
• Delete inbox deletes the inbox and its deliveries. Its address stops working at once, and later deliveries get a 404.

#Limits

The monthly count resets on the first of each month (UTC). When it runs out, deliveries get a 429 response with a Retry-After header, and the inbox counts how many it turned away so you know what you missed. Older deliveries beyond the per-inbox limit are removed as new ones arrive.