Skip to main content
Webhooks are the primary result-delivery channel: when a step verifies or a session concludes, Alentra POSTs a signed event to your configured URL. There is no supported polling loop. If a delivery is missed or dead-lettered, reconcile once with GET /v1/sessions/{id}.

Events

Every delivery also echoes the immutable workflow identity (id, name, revision, definition hash, and launch mode), plus caller metadata when supplied. See the event reference for full payloads.

Delivery guarantees

Stage-numbered

Events are created in state order and every step carries stage 0, 1, 2… . Network retries mean arrival order is not guaranteed; process by stage and make terminal handling tolerant of a late step delivery.

At-least-once

Delivery gets up to eight attempts with persisted exponential backoff, then becomes failed. Each event has a stable X-Alentra-Delivery-Id — dedupe on it so a retry is harmless.

Off the request path

Webhooks are queued and sent out-of-band, so a slow endpoint never blocks verification — but it does delay your delivery.

Fired after the result is durable

A step event is sent only after result, audit, applicable usage charge, and any document-evidence promotion commit, so a webhook always reflects persisted state.

Verifying signatures

Every delivery is signed with your business’s webhook secret (alentra_whsec_... from the dashboard). Always verify before trusting a payload. Each request carries: Recompute the HMAC over timestamp + "." + raw_request_body and compare in constant time. Use the raw bytes — re-serializing the JSON can change them and break the match.
Respond 2xx quickly and do heavy work asynchronously. A non-2xx (or timeout) is treated as a failed delivery and retried.

Rotating the secret

Generate or rotate your webhook secret from the dashboard. A session snapshots its webhook URL and secret when the session is created, and its queued deliveries keep that snapshot. During rotation, accept the old and new secret until in-flight sessions and retries have drained, then retire the old one.