Delivery, retries, deduplication, and ordering
Elicitra webhook events are delivered at least once. Treat the CloudEvent id as the durable idempotency key: verify the signature over the raw bytes, then atomically insert the id and accepted body or work item under a unique constraint before returning 2xx. A duplicate id must return 2xx without repeating business side effects.
See Verify webhook signatures for tested TypeScript and Python receiver examples.
Event modes, lifecycle, and ordering
Section titled “Event modes, lifecycle, and ordering”Elicitra exposes exactly these three lifecycle subscriptions:
com.elicitra.interaction.ended.v1at the first canonical terminal transition, withdata.lifecycleSequence: 1.com.elicitra.analysis.completed.v1when extraction commits asVALIDand the interaction reachesANALYSIS_READY, with sequence2.com.elicitra.analysis.failed.v1only after a terminal analysis failure and exhausted internal retries, also with sequence2. AnINVALIDextraction is not terminal.
Completed and failed analysis events are mutually exclusive for an interaction. Network delivery order is not guaranteed, so sequence is only a lifecycle hint. Store events independently and reconcile by interaction id and lifecycleSequence; do not wait indefinitely for sequence 1 before accepting sequence 2.
com.elicitra.automation.triggered.v1 is the fourth public event and has delivery mode conditional_destination. It is not available in endpoint lifecycle subscriptions. Elicitra sends it only when a configured conditional rule matches and selects that endpoint as its destination. It omits data.lifecycleSequence; deduplicate it by event id and use data.activation.executionId to correlate the selected action.
Every event id remains stable across retries and manual replay and is globally unique within Elicitra’s fixed CloudEvents source. For lifecycle events, Elicitra deterministically reserves one event for each organization, interaction, lifecycle slot, and schema version.
Retry schedule
Section titled “Retry schedule”Attempts are scheduled at absolute offsets from the first attempt:
| Attempt | Offset |
|---|---|
| 1 | immediately |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 6 hours |
| 7 | 24 hours |
| 8 | 72 hours |
Each non-zero offset has deterministic jitter of ±10%. A valid Retry-After selects the later of the normal schedule and the requested time, with the requested delay clamped between 1 minute and 24 hours.
- Any 2xx response succeeds.
410 Gonedisables the endpoint.- Redirects are never followed.
- Every other non-2xx response or network error retries until the delivery becomes dead letter.
- Each request times out after 10 seconds. Elicitra reads at most 64 KiB of response data and never persists the response body.
Replay and backfill
Section titled “Replay and backfill”A manual replay creates another delivery of the same CloudEvent with the same id. Replay is available for up to 30 days, and can expire earlier when source-data retention ends or the source is deleted; the UI exposes the effective replayExpiresAt.
Endpoint creation, reactivation, or tier upgrade does not backfill historical events or past rule matches. Test interactions (isTest) and MOCK mode do not emit lifecycle events. A scenario dry-run never sends an automation event. The endpoint UI test action sends synthetic, no-PII fixtures using the same three lifecycle event types.
Endpoint verification
Section titled “Endpoint verification”Verification is a signed control message, not a CloudEvent or a subscribable event. Elicitra sends Content-Type: application/json with the exact body shape { "challenge": "<random-128-bit-value>" }. Verify its Elicitra-Signature over the raw body like any event delivery. Activation requires both a 2xx delivery response and pasting the observed challenge back into Elicitra.
Endpoint URLs must use HTTPS on port 443. The URL is immutable; changing it creates and verifies a new endpoint.
Payload boundary and truncation
Section titled “Payload boundary and truncation”The maximum serialized payload is 256 KiB. Identifier, key, and label values are at most 256 characters; email is at most 320 characters; phone is at most 32 characters; business text is at most 8 KiB of UTF-8; collections contain at most 100 elements.
When optional content exceeds the limit, Elicitra deterministically removes collection elements from the tail and truncates text at a valid UTF-8 boundary. data.truncation is always present, and its omittedFields contains JSON pointers for affected fields. If even a minimum payload cannot be projected, Elicitra records and repairs a projection gap without converting a successful analysis into analysis.failed.
Transcripts, recordings, source quotes, raw model output, provider details, raw errors, debug/validation data, raw consent receipts, and arbitrary lead-card data are always excluded. See Security and privacy and the generated event reference.
Credits
Section titled “Credits”Lifecycle subscriptions, endpoint configuration and verification, synthetic tests, dry-runs, no-match evaluations, failed attempts, retries, and replay consume 0 credits. A conditional automation consumes 1 activation credit only when its delivery first succeeds; retries and replay do not charge it again.