Real-Time Webhooks: Delivery & Signing | 4D Sight Docs

What Webhooks Are For

The Impressions API is the system of record. Webhooks are how downstream systems learn about new impressions without polling — typically a data warehouse, an attribution platform, a finance system, or a real-time bidding decisioner. The right architecture for any high-volume integration is webhooks for freshness plus a nightly query-API reconciliation for completeness; relying on either alone is a known failure mode.

Delivery Topology

Webhook deliveries originate from a global edge tier with regional egress in North America, Europe, and Asia-Pacific. The delivery path is selected per event by minimum-RTT to the registered endpoint, so an endpoint in Frankfurt receives Europe-origin events from the Frankfurt edge, not from Virginia. The platform targets p99 end-to-end latency under 800 ms from frame ingest to webhook receipt and publishes the achieved figure on the public status page.

Endpoint Requirements

A receiving endpoint must accept POST over HTTPS with a valid TLS certificate, respond within 5 seconds, and return any 2xx status to acknowledge receipt. Non-2xx responses, timeouts, and connection failures all trigger the retry policy. Do not perform synchronous business logic inside the webhook handler — accept the event, write it to a durable queue, and return 200. Endpoints that block on downstream work are the single most common cause of dropped events.

Signing and Verification

Every webhook request includes three security headers:

X-4DS-Signature — HMAC-SHA256 of the raw request body, hex-encoded, using the endpoint signing secret.
X-4DS-Timestamp — Unix epoch seconds at the time of dispatch.
X-4DS-Event-Id — unique delivery identifier, stable across retries of the same event.

The receiver must (1) verify the signature using a constant-time comparison — not a string equality check, which leaks bytes via timing — and (2) reject any request whose timestamp is more than 5 minutes off from the receiver clock to prevent replay attacks. Signing secrets are rotatable from the console with an overlapping validity window of 24 hours.

Idempotency

X-4DS-Event-Id is the idempotency key. The same event id will be retried until the platform receives a 2xx response, so receivers must deduplicate. Storing the event id in a unique-indexed table at the start of the handler is sufficient; if the insert conflicts, return 200 immediately. This pattern handles every retry case correctly with no further bookkeeping.

Retry Policy

Failed deliveries are retried with exponential backoff starting at 30 seconds, doubling each attempt, up to a maximum interval of 1 hour. The retry window is 72 hours. Events that exhaust the retry window are written to the dead-letter queue and remain there for 30 days; they are visible in the console and replayable via the API.

Replay and Backfill

The replay API serves two cases. Backfill — when a new endpoint is registered and needs historical events — accepts a time range up to 90 days and streams the events to the registered endpoint at a configurable rate (default 100 events/second to protect downstream systems). Targeted replay — when a downstream system lost a window of data — accepts an explicit list of event ids and dispatches each one through the normal delivery path with a X-4DS-Replay: true header so receivers can route it differently if needed.

Observability

Per-endpoint delivery metrics are exposed in the console: success rate, p50/p95/p99 latency, retry rate, dead-letter rate, and signature failure rate. The same metrics are available via the /v1/webhooks/metrics endpoint for export into your observability stack. A signature failure rate above zero is always a bug — either a rotated secret has not been deployed, or the receiver is verifying incorrectly. Page on it.