Create a webhook subscription
const url = 'https://api.aerandil.com/v1/webhook-subscriptions';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"filter":{"object_types":["example"]},"start_position":"beginning","url":"https://example.com"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.aerandil.com/v1/webhook-subscriptions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "filter": { "object_types": [ "example" ] }, "start_position": "beginning", "url": "https://example.com" }'Register a receiver URL plus an optional object_types filter and a starting position. Returns the freshly generated signing_key exactly once — record it in your secret vault; subsequent reads expose only the fingerprint.
The start_position defaults to now: only events past the current head are delivered. Pick beginning to replay the full event log (useful for backfill / historical projection rebuilds).
Accepts Idempotency-Key (Stripe shape — see [draft-ietf-httpapi-idempotency-key-header]). A retry with the same key returns the same response, including the original signing_key.
Receiver URL must use HTTPS (loopback HTTP allowed in dev only — see validate_url in webhooks/handlers.rs).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Opaque idempotency token (Stripe-shape). Repeated POSTs with the same key replay the original response within the cache TTL rather than creating a duplicate object.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Filter narrowing what the worker delivers. Empty / absent means “every event in the tenant”.
object
Narrow to events whose object_type matches one of the listed api_names. For link events, either endpoint type matching counts — a filter of ["hospitality.reservation"] includes reservation_for_guest events.
Where the cursor starts. beginning replays from seq = 0 (full backfill); now / head skips historic events and delivers only what arrives after the subscription is created. Default now.
Receiver URL. HTTPS only (HTTP allowed only against loopback hosts for dev/test). Max 2048 chars.
Responses
Section titled “Responses”Subscription created. The signing_key is returned only here and on rotate-key — record it now or rotate to get a new one.
Subscription state plus the freshly minted signing key. Returned ONLY by create (POST .../webhook-subscriptions) and rotate (POST .../{id}/rotate-key); every other read surfaces fingerprints only. Customer captures the secret into their vault at this moment — there is no recovery path if it’s lost (the rotation flow is the recovery).
object
Resets to 0 on the first 2xx after any failure. Transitioning to dead_letter happens at 12 consecutive failures (~3-day retry window).
Filter narrowing what the worker delivers. Empty / absent means “every event in the tenant”.
object
Narrow to events whose object_type matches one of the listed api_names. For link events, either endpoint type matching counts — a filter of ["hospitality.reservation"] includes reservation_for_guest events.
Cursor into the event log. Advances to the highest seq read on every successful delivery — filtered-out events are still cursored past so the worker stays bounded under a narrow filter.
Earliest moment the worker will retry. Unset when the subscription is caught up; set in the future when an exponential-backoff retry is scheduled.
First 8 hex chars of sha256(primary_signing_key) — 16 chars in total. Exposed instead of the secret on every read.
Present during a key-rotation window. Cleared on promote-key.
Lifecycle of a webhook subscription. dead_letter is sticky — the worker stops attempting further deliveries until the customer PATCHes status back to active (and typically advances last_delivered_seq past the poison batch).
Receiver URL. HTTPS-only (except loopback in dev).
Set to true on a retry that the idempotency helper served from cache. Treat as advisory — the response body is the canonical state regardless.
32-byte HMAC key, hex-encoded (64 chars). Used to verify the Aerandil-Signature header on every inbound delivery to the receiver.
primary on create (the only key); secondary on rotate (added alongside the existing primary during the rotation window).
Example
{ "status": "active", "signing_key_slot": "primary"}Headers
Section titled “Headers”Always no-store.
/v1/webhook-subscriptions/{id} for the created resource.
Validation error — invalid_url, malformed body, unknown fields, or invalid Idempotency-Key.
Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.
object
object
Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).
Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.
Human-readable explanation of the failure.
Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).
Examplegenerated
{ "error": { "code": "example", "instance_id": "example", "message": "example", "parameters": "example" }}