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_at and the state in data, not arrival order.

Retry schedule#

Failed deliveries are retried up to 8 attempts in all:

AttemptDelay after the previous failure
1Immediately
21 minute
35 minutes
430 minutes
52 hours
66 hours
712 hours
824 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#

  1. Expose your local server with a tunnel, for example cloudflared tunnel --url http://localhost:3000 or ngrok http 3000.
  2. Add the tunnel's https URL as an endpoint in Webhooks.
  3. 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.