Integration checklist

Your endpoint is reachable over HTTPS (not plain HTTP, not localhost).

It accepts a POST with a JSON body.

It returns a 2xx status within a few seconds — before doing any slow work (database writes, calls to other services). See Set up a webhook endpoint.

Your endpoint URL is saved in the API section for the right topic and the right environment (staging while testing, production before go-live).

You verify the x-signature header on every request before trusting the body.

You hash the exact raw request bytes — not the parsed-and-re-serialized JSON. This is the most common first-integration bug; see Verify a webhook signature.

You use a timing-safe comparison to check the computed signature against the header.

A signature mismatch returns 401 and the request is discarded, not processed.

If you chose a non-default auth scheme (Bearer, Basic, API key), you verify that credential instead — see Register your endpoint & choose an auth type.

Your handler is idempotent — processing the same event twice is harmless.

You de-dupe every event — data.submission_id for form-submission, a content hash of data for policy-data.

For form-submission events specifically, you also de-dupe on data.submission_id.

You understand delivery is at-least-once: the same event can legitimately arrive more than once, and that's expected behavior, not a bug. See Delivery & de-duplication.

You download any file links (data.document_link, answers[].value[].url, data.acord.archive_url) as soon as the webhook lands — these links are time-limited and expire.

You don't store the link itself as your long-term reference — you store the file (or your own re-uploaded copy of it).

If a link has already expired, you re-fetch it via the submissions read API rather than treating it as permanently lost.

You send an Idempotency-Key header (a fresh UUIDv4 per operation) on every write — create, update, publish, archive.

You reuse the same key only when retrying the exact same operation, never across distinct operations.

You understand keys are honored for a limited window (24 hours), not forever.

Your code handles the standard error envelope (message, code, request_id, and errors[] on validation failures) rather than assuming success.

You log request_id (or trace_id, on submissions/webhooks) for every failure — you'll need it if you contact support.

List calls use cursor pagination correctly: you pass the cursor from next_cursor and stop when it's null, and you treat cursors as opaque values you never construct or parse yourself.

You handle 429 by backing off for the number of seconds in Retry-After, not by retrying immediately.

You've fired a test event at your staging URL for every topic you use, and confirmed your handler processes it correctly end to end.

You've checked the delivery log and seen successful (2xx) attempts, not just believed your own logs.

You've deliberately triggered a duplicate (replay a delivery from the log) and confirmed your handler doesn't double-process it.

You've swapped in your production API token, signing secret, and endpoint URL — and confirmed you're not still pointed at staging.

Integration checklist

Endpoint

Signature verification

De-duplication

Files

Writes (if you're creating or managing forms via the API)

Before you flip to production