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 Linktrail-Signature against the raw body and Linktrail-Timestamp using the documented signing procedure and an allowed timestamp window.
  3. Deduplicate by Linktrail-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 retention expired, follow the returned snapshot recovery procedure and record the history gap. A history-gap notice requires authenticated recovery; it cannot 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.