Delivery Status Callback

How external executors should record downstream delivery success or failure back into Numora.

Scope

This page explains how to write delivery results back into Numora when the downstream write is performed outside Numora.

Use this pattern only when:

your worker writes directly to the destination system
Numora is not executing the downstream write through dispatch
you need Numora to retain delivery audit history

If Numora performs the destination write internally, use dispatch instead of the callback path.

Callback Endpoint

POST /v1/documents/{id}/delivery

This endpoint records a delivery attempt for a single document.

Supported Status Values

succeeded
failed
skipped

Required Fields

Always required:

provider
status
execution_id
attempted_at

Required when status=succeeded:

external_record_id

Optional fields:

external_url
error_code
error_message

Typical status=skipped cases:

a lookup prerequisite such as supplier or team did not match
the worker intentionally completed without creating CRM records
you still want Numora to record a completed delivery attempt and stop automatic outbox retries

Success Example

curl -X POST "https://api.numora.example/v1/documents/4be38121-3791-4856-80d5-c57dbec2cf78/delivery" \
  -H "Authorization: Bearer $NUMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-request-id: delivery-callback-success-001" \
  -d '{
    "provider": "dynamics365",
    "status": "succeeded",
    "external_record_id": "crm-row-001",
    "execution_id": "n8n-4be38121-3791-4856-80d5-c57dbec2cf78",
    "attempted_at": "2026-03-24T03:00:00.000Z"
  }'

Failure Example

curl -X POST "https://api.numora.example/v1/documents/4be38121-3791-4856-80d5-c57dbec2cf78/delivery" \
  -H "Authorization: Bearer $NUMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-request-id: delivery-callback-failed-001" \
  -d '{
    "provider": "dynamics365",
    "status": "failed",
    "execution_id": "n8n-4be38121-3791-4856-80d5-c57dbec2cf78",
    "error_code": "crm_429",
    "error_message": "Dataverse rate limited",
    "attempted_at": "2026-03-24T03:00:00.000Z"
  }'

Skipped Example

Use skipped when the external executor completed intentionally without creating CRM records, for example because a supplier lookup returned no match.

curl -X POST "https://api.numora.example/v1/documents/4be38121-3791-4856-80d5-c57dbec2cf78/delivery" \
  -H "Authorization: Bearer $NUMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-request-id: delivery-callback-skipped-001" \
  -d '{
    "provider": "dynamics365",
    "status": "skipped",
    "execution_id": "n8n-4be38121-3791-4856-80d5-c57dbec2cf78",
    "error_code": "supplier_not_found",
    "error_message": "No supplier matched vendor_name \"Acme Supplies Ltd\".",
    "attempted_at": "2026-03-24T03:00:00.000Z"
  }'

Idempotency Rules

The callback is idempotent by execution_id.

Replaying the same execution_id with the same delivery data is accepted.
Replaying the same execution_id with different delivery data returns 409 conflict.

This allows safe retries when the external worker is unsure whether Numora received the first callback.

Delivery Audit Reads

Use this endpoint to inspect recorded attempts:

GET /v1/documents/{id}/delivery?provider=dynamics365&limit=20

This is the primary audit surface for callback-based integrations.

Document Status Impact

The callback affects downstream delivery visibility on the document resource.

Typical interpretations:

push_pending: the downstream write is still in progress or not yet confirmed
push_succeeded: a successful or intentionally skipped delivery attempt is recorded
push_failed: the latest delivery attempt failed

For status semantics, see Document Lifecycle.

When Not to Use This Endpoint

Do not call POST /v1/documents/{id}/delivery in the recommended Numora-managed dispatch mode.

In that mode:

Poll the outbox.
Call dispatch.
Let Numora perform the write and update document status.

Delivery Status Callback

On this page