Idempotency, retries and delivery order

Building with AI? Connect it to your account over MCP: it checks your setup, creates webhooks and templates with your confirmation and writes the code for you. See how →

Sending: always send an Idempotency-Key on POST /v1/messages. You generate it, we don't hand it to you: a fresh UUID v4 per message you want to send (not per HTTP attempt — reusing it on a retry is the whole point). A retry with the same key returns the same record (200) instead of duplicating. The source of truth is MariaDB (we persist before enqueuing), so a 202 is never lost even if Redis goes down.

Delivery (webhooks): 5 attempts in total: the first one and 4 retries at 1m → 5m → 30m → 2h. To deduplicate, use the envelope id (evt_…): it is the same on every retry and every endpoint. The X-Connect-Delivery-Id identifies the delivery to ONE endpoint, not the event. After 20 consecutive failures the endpoint is auto-disabled (critical alert) and you re-enable it from the panel.

Order: delivery order is NOT guaranteed (retries + concurrency). Order it yourself by createdAt (ISO-8601 Z) + sequence (monotonic per connection; 0 when connection is null).

Your endpoint must be idempotent: the same delivery can arrive more than once.