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.