NuggetAPI referenceAPI consoleOpenAPI

Webhooks

Extraction, OCR, and Locate support terminal notifications. Classification jobs currently use polling only. For JSON document requests supply:

{
  "callback": {
    "url": "https://your-service.example/nugget/events",
    "signing_secret": "replace-with-a-random-secret-at-least-32-bytes"
  },
  "client_metadata": {"workflow_id": "your-workflow-id"}
}

This is a request fragment; also supply the operation's required fields. The receiver must be public HTTPS. Nugget rejects private/reserved addresses and does not follow redirects. A callback selects async execution. Metadata alone does not; metadata is limited to a 4096-byte serialized JSON object.

Verify before parsing

X-Nugget-Signature is sha256=<lowercase hex>, the HMAC-SHA256 of the exact raw body bytes using your signing secret. Do not verify a reserialized JSON body.

import hashlib
import hmac

def verify_callback(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

After signature verification, enforce an application replay window using the signed callback.updated_at, deduplicate terminal events using the signed event_id (also returned as X-Nugget-Event-Id), and enqueue your own downstream work before returning a prompt 2xx. X-Nugget-Delivery-Id identifies an attempt, not the stable event.

Delivery is at least once; duplicates are possible. The delivery worker has a three-execution retry budget persisted across replacement queue tasks; permanent rejection stops earlier. The signed event identifies the notification type. Reconciliation repairs lost callback enqueue notifications. Polling is the recovery path if a webhook is delayed or absent. Callback-delivery failure does not change a successful document job into a failed document job. Receiver rejection and unsafe destinations can stop delivery; do not assume every non-2xx response is retried.

OCR notifications omit the large OCR result; fetch it through the polling URL. Extraction and Locate can include results. See the OpenAPI webhook schema for headers and the job-specific response schemas for exact payloads.