Skip to navigation
APIWebhook Events

extraction.ready

Fires once per document, the moment its extraction is queryable in the shape you should build on, and the usual cue to pull line items. For a bank statement it is held back until counterparty enrichment lands, or until the grace window elapses without it (enrichment says which).

Headers

SpreadSpace-SignaturestringRequired

Signature over the exact request body: t=<seconds since the Unix epoch>,v1=<lowercase hex HMAC-SHA256 of "{t}.{body}" keyed with your endpoint's signing secret>. Verify it before trusting the body, and reject a t more than five minutes from your own clock. During a secret rotation both the new and the previous secret verify for 24 hours; each delivery is signed with exactly one.

SpreadSpace-Event-IdstringRequiredformat: "^evt_[0-9a-f]{24}$"

The event id, identical to the body’s id. Stable across retries and replays, and shared by every endpoint one event fans out to. Delivery is at-least-once, so dedupe on it.

Payload

The payload of this webhook request is an object.
idstringRequiredformat: "^evt_[0-9a-f]{24}$"

Event id: evt_ plus 24 lowercase hex characters. Also sent as the SpreadSpace-Event-Id header. Stable across retries and replays, so dedupe on it.

typeenumRequired
Always this event type on this body.
Allowed values:
createdlongRequired

Seconds since the Unix epoch at which the event was created server-side. Seconds, not milliseconds. Deliveries are not ordered; reconcile on this.

tenant_idstringRequired
The workspace the event belongs to. Reject a delivery whose tenant does not match the endpoint you registered.
livemodebooleanRequired

true for live activity, false for test mode (an ss_test_ key or the sandbox simulator). Branch on it to route test deliveries to a staging handler.

dataobjectRequired

The data object on an extraction.ready delivery, sent once per document the moment its extraction is queryable in the shape you should build on. It is the usual cue to pull line items, and narrower than document.processed, which also covers the classification-only and failure paths.

A bank statement can be enriched shortly after it is ingested. So that what you fetch on this event is what you keep, extraction.ready for such a statement is held back until the enrichment lands (enrichment is complete), or until a grace window elapses without it (timed_out, and an extraction.updated follows if it arrives later). Every other document fires at ingestion with not_applicable. document.processed is never held back.

Response

2XX
Return any 2xx within 5 seconds. A 4xx other than 429 stops retries for that delivery. 429, 5xx, network errors and timeouts are retried, up to 12 attempts in all.