Skip to main content
Webhooks notify an HTTPS receiver about source or destination events, or periodic digests. Delivery requires the hosted environment’s transport configuration. Read capability status before expecting an endpoint to send.

​
Prepare the receiver

  1. Accept the raw HTTP request body before JSON parsing.
  2. Verify AgentLinkOps-Signature against the raw body and AgentLinkOps-Timestamp using the documented signing procedure and an allowed timestamp window. Each delivery also carries Linktrail-Signature, Linktrail-Timestamp, Linktrail-Delivery-Id and Linktrail-Event-Type with identical values for receivers written against the working name; those aliases are removed in a separate dated release after pilot customers are notified (DP-0029-T05).
  3. Deduplicate by AgentLinkOps-Delivery-Id.
  4. Persist accepted work before acknowledging success, then process it outside the request when needed.
Webhook reference defines the signed bytes, headers, payloads and recovery notices. Re-encoding parsed JSON before verification changes the signed input.

​
Create and verify the subscription

Call create_webhook with your HTTPS URL, intended project scope, feeds and delivery mode. Store the returned signing secret in the receiver’s secret store: it appears once. A new endpoint starts at the current sequence, so retrieve earlier retained events through their authenticated feeds. Generate an authorized event in the selected scope and inspect list_webhook_deliveries. Confirm your receiver accepted the signature and stored the delivery identifier. Endpoint creation alone proves no delivery.

​
Recover after a failure

Delivery is at least once. Use list_webhooks to inspect state and disable reason, and delivery history for HTTP status and attempt details. A receiver response of 410 disables delivery. Correct the receiver before reactivating the endpoint. Read missed source events and destination events with separate cursors. If a cursor falls outside retention, the feed returns CURSOR_EXPIRED with a snapshot endpoint and a resume cursor: export the snapshot, record the gap and resume from that cursor. The deployed release sends no webhook notice for that gap, and no recovery step can reconstruct deleted event history. Rotate with rotate_webhook_secret. During overlap, both active secrets sign requests. Update and verify the receiver before retiring the older secret. Use sync and export for ledger recovery and troubleshooting for persistent failures.