Webhooks: the receiver contract
What an endpoint that receives ErectOS webhooks must do, and what ErectOS guarantees in return. This is the public contract for the delivery fields deliveryId, eventId and attempt.
What ErectOS sends
One HTTPS POST per delivery attempt, Content-Type: application/json.
The body (the signed, authoritative copy)
{
"event": "rfi.created",
"data": { "...": "the event payload" },
"organizationId": "org_…",
"deliveredAt": "2026-11-01T18:00:00.000Z",
"deliveryId": "01993b6e-…",
"eventId": "01993b6d-…",
"attempt": 1
}- event
- The event name (dot form, e.g.
rfi.created). Unchanged. - data
- The event payload. For a domain event,
data.idis stable and equalseventId, anddata.occurredAtis when the event was written, the same on every redelivery. Neither replacesdeliveryIdas your idempotency key. - organizationId
- The sending organisation. Unchanged.
- deliveredAt
- When THIS attempt was sent (ISO 8601). Unchanged; it differs on every attempt.
- deliveryId
- The identity of the delivery: the same on every attempt of it and on a manual redelivery. Your idempotency key. New.
- eventId
- The identity of the business event: the same across every endpoint it was sent to and across redeliveries. Use it to order or ignore stale updates. New.
- attempt
- 1 for the first attempt, then 2, 3, …; a manual redelivery is the previous attempt + 1. New.
The three new fields are additive: no existing field changed name, value or position.
The headers
Header names are case-insensitive.
- X-Erectos-Signature
t=<unix seconds>,v1=<hex HMAC-SHA256>(see below). During a secret rotation's grace window it carries twov1=values, the current secret's first.- X-Erectos-Timestamp
- The
tof the signature. - X-Erectos-Event
- The event name.
- X-Erectos-Delivery-Id
- Mirror of the body's
deliveryId. - X-Erectos-Event-Id
- Mirror of the body's
eventId. - X-Erectos-Attempt
- Mirror of the body's
attempt. - X-Erectos-Redelivery
trueon a manual redelivery (an operator's retry or replay); absent otherwise.
The header mirrors exist so a receiver can route before it parses. Only the body is signed: when a header and the body disagree, the body wins, and an unverified body must be ignored.
The signature
X-Erectos-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>v1isHMAC-SHA256(secret, "<t>.<raw body>"), hex-encoded, where<raw body>is the exact bytes received (verify before any JSON parsing or re-serialisation).- Reject the request when
tis more than 5 minutes from your clock. - Compare in constant time.
- Accept the request if ANY
v1value matches (rotation grace window).
What the receiver must do
- 1Verify the signature first.
Refuse (any 4xx) and do nothing else when it fails or
tis outside the tolerance. - 2Check deliveryId against a store of processed ids.
Keep that store for at least 72 hours. If you use manual redelivery or resend an outage after re-enabling an endpoint, keep ids for 30 days, or check a redelivery against
eventIdand your own records. - 3A deliveryId you have already processed: answer 2xx and do not process it again.
- 4Otherwise process it once.
Record its
deliveryId, and answer 2xx. - 5Answer within the timeout.
The timeout is 10 seconds. Do slow work after you answer (queue it on your side).
- 6Treat delivery as at-least-once and unordered.
The same delivery can arrive more than once (a retry after a lost answer, a manual redelivery) and two events can arrive out of order. Use
eventIdand your own record of the entity's state to order updates or to ignore a stale one.
ErectOS tests its delivery against a reference receiver written to this contract: it processes three attempts of one delivery exactly once and refuses a body whose deliveryId was altered.
Manual redelivery
A manual redelivery (an operator's retry or replay) keeps the same deliveryId you already saw; only attempt advances, to the previous attempt + 1, and the header X-Erectos-Redelivery: true is added. A receiver that already processed that deliveryId answers 2xx and does not process it again.
What ErectOS guarantees
A failed attempt is retried with exponential backoff (5 s base, ±20% jitter, capped at 6 h between attempts) within a 24-hour window. Every retry carries the same deliveryId and eventId and the next attempt.
Only attempt advances (the previous attempt + 1), and X-Erectos-Redelivery: true is added.
2xx is delivered. A 4xx other than 408 or 429 is permanent: the delivery is not retried (fix the receiver, then use a manual redelivery). 408, 429, 5xx, a timeout and a connection failure are retried.
A 3xx is a failed attempt.
A retried attempt never counts against your endpoint; only a delivery that ends dead (its retries ran out, or the receiver answered a permanent status) does. By default the endpoint is disabled only when 5 deliveries in a row have ended dead AND none has succeeded for at least 24 hours (your organisation's admins can change these); any 2xx resets the count. Your organisation's admins are notified once when it happens, and deliveries still queued for the endpoint are recorded as dead, never silently dropped. When you re-enable the endpoint from its settings, you can resend the deliveries that failed during the outage and are still on record: each resend carries the original deliveryId and eventId, the next attempt, and X-Erectos-Redelivery: true, and gets a fresh retry window.
ErectOS only sends to public addresses (private, loopback, link-local and metadata addresses are refused on the connection path, DNS rebinding included).
In short: verify the signature, key idempotency on deliveryId, order with eventId, and answer 2xx fast.