{"componentChunkName":"component---src-templates-simple-markdown-js","path":"/docs/ai/document-ai/events-and-webhooks/","matchPath":"","result":{"data":{"markdownRemark":{"html":"

Document Events and Webhooks

\n

Subscribe to document lifecycle events when your integration should react without polling.

\n

Document AI publishes three versioned event types:

\n\n

Processing completion, failure, skip, and oversize outcomes appear as document updates. There are no separate document_intelligence.* completion or failure events.

\n

Configure a webhook

\n

Use Shipwell's webhook configuration API to subscribe an HTTPS endpoint to the document events your application needs.

\n

See Use Webhooks for:

\n\n\n

Event payload

\n

Webhook deliveries use the standard Shipwell event envelope. The details object contains the document-specific data.

\n
\n
",\n "occurred_at": "2026-07-15T12:00:00Z",\n "source": {\n "user_id": "",\n "company_id": "",\n "request_id": "",\n "publishing_system": "document-store",\n "environment": "sandbox"\n },\n "event_name": "document.updated.v1",\n "details": {\n "id": "",\n "resource_type": "document",\n "self_link": "/document-store/documents//",\n "status": "completed",\n "type": "bill_of_lading",\n "filename": "bol.pdf",\n "description": "Bill of lading for a completed shipment.",\n "content_type": "application/pdf",\n "size_bytes": 1832102,\n "associations": [\n {"entity_type": "shipment", "entity_id": "SW-1001"}\n ],\n "old_data": {"status": "processing"},\n "new_data": {"status": "completed"},\n "run_id": "",\n "result_count": 1,\n "url": "",\n "url_expires_at": "2026-07-15T12:15:00Z"\n }\n}`, `57854011897236140000`)\"\n >\n
Copy
\n
Copied
\n
\n 
{\n  \"id\": \"<event-id>\",\n  \"occurred_at\": \"2026-07-15T12:00:00Z\",\n  \"source\": {\n    \"user_id\": \"<user-id>\",\n    \"company_id\": \"<company-id>\",\n    \"request_id\": \"<request-id>\",\n    \"publishing_system\": \"document-store\",\n    \"environment\": \"sandbox\"\n  },\n  \"event_name\": \"document.updated.v1\",\n  \"details\": {\n    \"id\": \"<document-id>\",\n    \"resource_type\": \"document\",\n    \"self_link\": \"/document-store/documents/<document-id>/\",\n    \"status\": \"completed\",\n    \"type\": \"bill_of_lading\",\n    \"filename\": \"bol.pdf\",\n    \"description\": \"Bill of lading for a completed shipment.\",\n    \"content_type\": \"application/pdf\",\n    \"size_bytes\": 1832102,\n    \"associations\": [\n      {\"entity_type\": \"shipment\", \"entity_id\": \"SW-1001\"}\n    ],\n    \"old_data\": {\"status\": \"processing\"},\n    \"new_data\": {\"status\": \"completed\"},\n    \"run_id\": \"<run-id>\",\n    \"result_count\": 1,\n    \"url\": \"<temporary-download-url>\",\n    \"url_expires_at\": \"2026-07-15T12:15:00Z\"\n  }\n}
\n
\n

Fields can be absent when they do not apply. For example, run_id and result_count are associated with processing updates, while delete_kind can appear on a delete event.

\n

Treat details.url as a temporary, sensitive convenience URL. Store details.id and request a new download URL when needed.

\n

Event behavior

\n

document.created.v1

\n

Sent after a document is created.

\n

The initial status can be:

\n\n

AI-generated fields may not be available yet because processing is asynchronous.

\n

document.updated.v1

\n

Sent when document data or processing state changes. Processing outcomes are represented through details.status, commonly:

\n\n

Use old_data and new_data when you need to understand the changed fields. On a completed processing update, use run_id to retrieve the run and its results.

\n

document.deleted.v1

\n

Sent after document deletion. The payload identifies the deleted document and can include delete_kind.

\n

Do not attempt to use a temporary download URL from a delete event.

\n

Recommended handler

\n
    \n
  1. \nVerify the webhook signature using the raw request body.\n
    2. \n
  2. \nPersist the delivery and return a \n2xx\n response promptly.\n
    3. \n
  3. \nProcess the event asynchronously.\n
    4. \n
  4. \nUpsert state by \ndetails.id\n.\n
    5. \n
  5. \nRetrieve the current document or run before performing downstream work.\n
    6. \n
\n

Example routing logic:

\n
\n
\n
Copy
\n
Copied
\n
\n 
def handle_document_event(event):\n    event_name = event[\"event_name\"]\n    details = event[\"details\"]\n\n    if event_name == \"document.updated.v1\" and details.get(\"status\") == \"completed\":\n        enqueue_result_sync(\n            document_id=details[\"id\"],\n            run_id=details.get(\"run_id\"),\n        )\n    elif event_name == \"document.deleted.v1\":\n        enqueue_document_removal(document_id=details[\"id\"])
\n
\n

Delivery safety

\n

Webhook delivery is at least once, and events can arrive out of order.

\n","headings":[{"value":"Document Events and Webhooks","depth":1},{"value":"Configure a webhook","depth":2},{"value":"Event payload","depth":2},{"value":"Event behavior","depth":2},{"value":"document.created.v1","depth":3},{"value":"document.updated.v1","depth":3},{"value":"document.deleted.v1","depth":3},{"value":"Recommended handler","depth":2},{"value":"Delivery safety","depth":2}]},"contentItem":{"data":{"lastModified":"2026-07-17T16:00:10.000Z","enableToc":null,"disableLastModified":null,"tocMaxDepth":null,"requestLogin":false}},"siteConfig":{"enableToc":true,"disableLastModified":false,"tocMaxDepth":4}},"pageContext":{"matchPath":"","id":"971f0aeb-0f53-5d6e-9100-40a88d688207__redocly content/docs/ai/document-ai/events-and-webhooks/","seo":{"title":"Events and Webhooks","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"docs/ai/document-ai/events-and-webhooks.md","pageBaseUrl":"/docs/ai/document-ai/events-and-webhooks","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Document Events and Webhooks","id":"document-events-and-webhooks"},{"depth":2,"value":"Configure a webhook","id":"configure-a-webhook"},{"depth":2,"value":"Event payload","id":"event-payload"},{"depth":2,"value":"Event behavior","id":"event-behavior"},{"depth":3,"value":"document.created.v1","id":"documentcreatedv1"},{"depth":3,"value":"document.updated.v1","id":"documentupdatedv1"},{"depth":3,"value":"document.deleted.v1","id":"documentdeletedv1"},{"depth":2,"value":"Recommended handler","id":"recommended-handler"},{"depth":2,"value":"Delivery safety","id":"delivery-safety"}]},"data":{"title":"Events and Webhooks"},"catalogInfo":null,"link":"/docs/ai/document-ai/events-and-webhooks/","sidebarName":"developerPortal","isLanding":false,"showPrevButton":null,"showNextButton":null,"apiVersions":null,"apiVersionId":null,"isDefaultApiVersion":null}},"staticQueryHashes":["1123603147","1302185487","1344209882","1398840060","1520077861","1975142765","2667623876","2950305614","3240152602","3743992808","561138138"]}