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.
{
"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.
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 asynchronouslyReplay 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.