DocsDeveloper integration

Webhook events, signing and delivery draft

Define event envelopes, signatures, replay protection, deduplication and recovery.

Purpose and proposed events

Webhooks notify external systems of state changes; receivers retrieve details through authorized queries. Proposed events include task-request.status-changed, delivery.submitted and connection.revoked. These are design names, not evidence of subscriptions or delivery services. Implement and validate subscription management and secret issuance first.

Event envelope

Send minimal metadata rather than task bodies or sensitive outputs. The event ID supports business deduplication; deliveryId identifies an attempt. Preserve the event ID across retries. Use ISO 8601 timestamps with timezone.

json
{
  "specVersion": "0.1",
  "id": "evt_example",
  "deliveryId": "dlv_example_1",
  "type": "task-request.status-changed",
  "occurredAt": "2026-11-16T08:00:00Z",
  "companyId": "co_example",
  "data": {
    "resourceId": "tr_example",
    "revision": 3,
    "status": "awaiting_review"
  }
}

Proposed signature contract

Assign a separate secret per subscription and use HMAC-SHA256. Proposed headers are DigitalHe-Delivery-Id, DigitalHe-Timestamp and DigitalHe-Signature, with v1= followed by a lowercase hex digest. Sign timestamp, a dot, deliveryId, a dot, then raw request body bytes. Never verify reserialized JSON. Both sender and receiver must implement this contract.

text
message = UTF8(timestamp + '.' + deliveryId + '.') || rawBodyBytes
signature = 'v1=' + hexLower(HMAC_SHA256(subscriptionSecret, message))

Verify timestamp format and allowed skew
Recompute signature over the raw bytes
Compare equal-length digests in constant time
Parse JSON; require body.deliveryId == header delivery ID
Authorize subscription and company; persist event ID uniquely
Acknowledge after durable enqueue; process asynchronously

Replay protection, rotation and deduplication

A 5-minute timestamp tolerance is a discussion starting point, finalized for network and clock conditions. Retry with a fresh timestamp and delivery identifier but the same event ID. Persist event IDs for deduplication. Bound key overlap during rotation and exclude keys and signatures from public logs, retaining redacted identifiers and verification outcomes.

Acknowledgment, retries and ordering

Return 2xx after durable enqueue and process asynchronously. A valid signature followed by persistence failure returns a retryable error. The sender retries timeouts, 429 and 5xx within bounds, pausing and alerting for other 4xx. Publish timeout, retry intervals, retention and attempts before release. Use at-least-once delivery without ordering or exactly-once guarantees; consumers use resource revisions to detect stale events.

Recovery and integration checks

The sender needs failed-delivery records, pause/resume, authorized replay and status queries. Receivers must handle duplicates, ordering changes, queue failures, expired keys and restarts. Restrict subscription destinations to approved HTTPS endpoints, validating hosts and redirects to prevent SSRF. Production use requires implementing and verifying these mechanisms.

All documentationNext guide

Still have a question?

Explore expert support