Webhooks
Delivery, retries and best practices
Webhook delivery guarantees, the retry schedule, automatic disabling and how to build a reliable handler.
Available on Growth and above.
Delivery#
- A delivery succeeds when your endpoint returns 2xx within 10 seconds.
- Delivery is at least once: the same event can arrive more than once. Deduplicate on
id. - Events can arrive out of order. Use
created_atand the state indata, not arrival order.
Retry schedule#
Failed deliveries are retried up to 8 attempts in all:
| Attempt | Delay after the previous failure |
|---|---|
| 1 | Immediately |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 6 hours |
| 7 | 12 hours |
| 8 | 24 hours |
Disabled endpoints#
An endpoint that has failed continuously for 3 days is disabled, and the workspace owners are told by email and notification. Fix the endpoint, then re-enable it from Webhooks.
Best practices#
- Verify every signature and reject old timestamps.
- Respond fast: store the event, return 200, and do the work in a background job.
- Make handlers idempotent: record processed
ids and skip repeats. - Subscribe only to the events you need.
- Treat the payload as a notification. If you need the latest state, look it up rather than relying on order.
Testing locally#
- Expose your local server with a tunnel, for example
cloudflared tunnel --url http://localhost:3000orngrok http 3000. - Add the tunnel's https URL as an endpoint in Webhooks.
- Click Send test event to receive a
ping, then trigger real events (invite a test partner, record a test conversion).
To unit-test your handler, sign a sample payload yourself:
Node
import crypto from "node:crypto";
const body = JSON.stringify({ id: "evt_test", type: "ping", created_at: new Date().toISOString(), api_version: "2026-11-20", workspace: { id: "ws", slug: "acme" }, data: { message: "Test event from Intrio" } });
const t = Math.floor(Date.now() / 1000);
const v1 = crypto.createHmac("sha256", process.env.INTRIO_WEBHOOK_SECRET!).update(`${t}.${body}`).digest("hex");
await fetch("http://localhost:3000/api/intrio/webhooks", {
method: "POST",
headers: { "content-type": "application/json", "intrio-signature": `t=${t},v1=${v1}` },
body,
});Last updated 20 November 2026. Building with an AI assistant? Point it at /docs/llms-full.txt.