Back to Docs

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)

Example body
{
  "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.id is stable and equals eventId, and data.occurredAt is when the event was written, the same on every redelivery. Neither replaces deliveryId as 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 two v1= values, the current secret's first.
X-Erectos-Timestamp
The t of 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
true on 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

Signature header format
X-Erectos-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>
  • v1 is HMAC-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 t is more than 5 minutes from your clock.
  • Compare in constant time.
  • Accept the request if ANY v1 value matches (rotation grace window).

What the receiver must do

  1. 1
    Verify the signature first.

    Refuse (any 4xx) and do nothing else when it fails or t is outside the tolerance.

  2. 2
    Check 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 eventId and your own records.

  3. 3
    A deliveryId you have already processed: answer 2xx and do not process it again.
  4. 4
    Otherwise process it once.

    Record its deliveryId, and answer 2xx.

  5. 5
    Answer within the timeout.

    The timeout is 10 seconds. Do slow work after you answer (queue it on your side).

  6. 6
    Treat 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 eventId and 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

At least once, with a stable deliveryId.

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.

A manual redelivery keeps the deliveryId you already saw.

Only attempt advances (the previous attempt + 1), and X-Erectos-Redelivery: true is added.

Which answers are retried.

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.

Redirects are never followed.

A 3xx is a failed attempt.

Circuit breaker.

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.

Egress safety.

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.