Guide
Hold webhooks while your tunnel is offline
Keep the webhooks that arrive while your computer is asleep or the connector is stopped, and deliver them when the tunnel is back.
- Applies to
- Starter and higher; durable tunnels without a password or token
- Time
- About 10 minutes
- What it changes
- Stores requests for your tunnel while it is offline.
- Last reviewed
- , by Product documentation
Before you begin
- A durable tunnel that receives webhooks.
- A plan that includes the inbox (Starter and higher).
- A tunnel with no password and no token, because a webhook sender cannot send either.
What to know before you start
- A held request keeps the full request, including its headers and body, in unencrypted storage until it is delivered or reaches its holding time, and may contain personal data or credentials the sender included.
- The inbox does not guarantee delivery: a request can be lost if it is larger than the limit, if the inbox is full, or if the holding time passes before your tunnel is back.
- A provider's signature may expire before the request is delivered.
Steps
Step 1. Open the tunnel and find Webhook inbox.
You should see: You see a switch and a box for webhook paths.
Step 2. Turn on Hold webhook requests while this tunnel is offline, list your webhook paths and save.
Webhook paths /webhooks/stripe /webhooks/githubEnter one path per line, up to 10. A path covers itself and everything under it. Only POST, PUT and PATCH requests to these paths are held.
You should see: The dashboard says the inbox is saved and that it applies within 30 seconds.
Step 3. Stop the connector and send a webhook.
You should see: The sender gets a 202 reply, and the dashboard says a request is waiting for the tunnel.
Step 4. Start the connector again.
You should see: The held requests are delivered, one at a time and in order, about two a second. The list under Webhook inbox shows each as delivered, with the status your app answered.
You are done when
- A webhook sent while the connector was stopped is delivered to your app after you start the connector again.
If something goes wrong
- The inbox cannot be turned on.
- The inbox needs a tunnel without a password or token. Remove the protection, or use the provider's own retries.
- A webhook was not held.
- Webhooks are held only while the tunnel has no live connector, only for POST, PUT and PATCH, and only for the paths you listed. Check the path spelling, and that the setting was saved at least 30 seconds ago.
Undo or clean up
- Turn off Hold webhook requests while this tunnel is offline and save. Requests already held are still delivered.
Good to know
| What | Limit |
|---|---|
| Requests held per tunnel | 100. The 101st gets a 503 with a Retry-After, so the provider tries again later. |
| Size of one request body | 64 KiB. A larger request gets a 413. |
| How long a request is kept | 24 hours on Starter and Pro, 72 hours on Team and Business. |
| Delivery attempts | Up to three. A reply below 500 counts as delivered, even if your app refused it. Anything else is retried after a wait, then marked failed. |
When a request is delivered, fails or expires, its headers and body are deleted and only a short record stays for 24 hours so you can see what happened. The dashboard never shows request content and removes the query string from paths.
Related
This page is part of Automate and integrate. Still stuck? Contact support.