Webhook delivery

Dockt delivers signed JSON events to active webhook endpoints in a Workspace.

Subscription events

Subscribe an endpoint to any of these event types:

• assessment.completed
• document.completed
• document.failed

POST /v1/webhooks/{webhookId}/test sends a targeted webhook.test event without adding it to the subscription list.

Delivery headers

Header	Meaning
X-Dockt-Event-Id	Stable event ID used across retries.
X-Dockt-Event-Type	Event type, equal to the JSON body type.
X-Dockt-Timestamp	ISO 8601 timestamp included in the signed message.
X-Dockt-Signature	v1= followed by a lowercase hexadecimal HMAC-SHA256 digest.

Event envelope

An Assessment completion event has this shape:

{
  "object": "event",
  "id": "evt_example1042",
  "type": "assessment.completed",
  "created_at": "2026-08-06T09:35:00Z",
  "data": {
    "assessment_id": "ast_example1042",
    "decision_id": "dec_example1042",
    "decision": "compliant",
    "signal": "green"
  }
}

Document lifecycle events include a compact Document summary in data.document. Fetch the canonical Document for complete evidence detail.

The top-level webhooks section in OpenAPI JSON defines every receiver schema.

Signature contract

Verify X-Dockt-Signature as HMAC-SHA256 over:

<X-Dockt-Timestamp>.<raw request body>

Use the endpoint’s one-time signing secret, lowercase hexadecimal encoding, the v1= prefix, and a constant-time comparison. Reject timestamps outside a five-minute replay window.

Implement a webhook receiver

Delivery behavior

• Delivery is at least once.
• Event ordering isn’t guaranteed.
• Retries keep the same event ID and body.
• Any 2xx response acknowledges the event.
• Non-2xx responses and timeouts retry up to 10 total attempts.
• Retry delays increase exponentially and are capped at about 60 seconds.
• The default request timeout is 10 seconds.

Persist or enqueue a verified event before acknowledging it. Deduplicate side effects by event ID.

Delivery health

Webhook endpoint reads include a delivery summary with the latest event type, result, attempt time, and successful-delivery time. The fields are null before the first attempt.

The summary describes only the latest persisted delivery health. Use your receiver’s event log and canonical API reads for complete recovery and reconciliation.