Notification destinations

Notification Destinations are reusable Workspace-owned targets for asynchronous events. Event routes select which destinations receive each supported event type.

Resource model

Create a destination with POST /v1/notification-destinations. Every destination has common lifecycle and delivery fields:

• id, label, and status
• type and a matching type-specific configuration object
• delivery health
• created_at and updated_at

Dockt supports one destination type:

• webhook: Delivers a signed JSON event to an HTTPS URL.

Event routes

Use PUT /v1/notification-routes/{eventType} with notification_destination_ids to replace the destinations selected for one event type. An empty list disables the route. A route accepts up to 20 unique destinations from the active Workspace.

Use PATCH /v1/notification-routes/{eventType} with notification_destination_id and subscribed to add or remove one destination. This operation preserves other destinations, including during concurrent edits. Repeating the same subscription change is safe.

Supported event types are:

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

Disabled destinations retain route references and silently suppress delivery. You can’t delete a referenced destination.

POST /v1/notification-destinations/{notificationDestinationId}/test sends a targeted notification_destination.test event without changing a production route.

Webhook destinations

A destination with type: "webhook" stores its URL under webhook.url. Creation and explicit secret rotation return its signing secret once. Reads never return the secret.

Use a public HTTPS URL that can read the raw request body. Follow Receive webhooks for a complete receiver implementation.

Webhook URLs must use port 443, a DNS hostname, and no embedded credentials or fragment. Dockt checks both IPv4 and IPv6 DNS answers when creating or changing the URL and before every delivery. Private, loopback, link-local, metadata, multicast, and reserved addresses are rejected, even behind a public-looking hostname. DNS lookup failures reject URL writes and prevent delivery. Redirects are never followed; configure the final receiver URL directly.

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

{
  "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"
  }
}

Dockt sends assessment.reassessed only when a scheduled reassessment changes the stable Decision, requirements, or Findings. Document lifecycle events include a compact Document summary in data.document. Fetch the canonical resource before applying an important side effect.

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 destination’s one-time signing secret, lowercase hexadecimal encoding, the v1= prefix, and a constant-time comparison. Reject timestamps outside a five-minute replay window.

Delivery behavior

• Delivery is at least once and unordered.
• One resolved destination has one independently retried delivery job.
• 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

Destination reads include a delivery summary with the latest event type, result, attempt time, and successful-delivery time. Fields are null before the first attempt. Use receiver logs and canonical resource reads for complete recovery.