> For the complete documentation index, see [llms.txt](https://docs.insurgrid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.insurgrid.com/testing/integration-checklist.md). # Integration checklist **What it's for:** a final pass before you register a production URL. It covers both kinds of InsurGrid webhooks — policy data (`client-submission`) and form submissions (`form-submission`) — plus the API calls you make if you're building or reading forms directly. Skip items that don't apply to your integration. Work through this in [sandbox](/testing/sandbox.md) first. Nothing here should be new if you followed a [quickstart](/quickstarts/a-receive-policy-data.md) — it's a checklist, not a tutorial. ## Endpoint * [ ] 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](/get-started/04-webhook-endpoint.md). * [ ] Your endpoint URL is saved in the **API section** for the right **topic** and the right **environment** (staging while testing, production before go-live). ## Signature verification * [ ] 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](/guides/signing-verification.md). * [ ] 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](/guides/register-endpoint-auth-types.md). ## De-duplication * [ ] 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](/guides/delivery-dedup.md). ## Files * [ ] 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. ## Writes (if you're creating or managing forms via the API) * [ ] 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. ## Errors, pagination & rate limits * [ ] 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. ## Before you flip to production * [ ] 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. Once every relevant box is checked, you're ready to go live. See [Sandbox & testing → Promoting to production](/testing/sandbox.md#promoting-to-production). ## Related * [Sandbox & testing](/testing/sandbox.md) * [Troubleshooting: my webhook isn't arriving](/testing/troubleshooting.md) * [Verify a webhook signature](/guides/signing-verification.md) * [Delivery & de-duplication](/guides/delivery-dedup.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.insurgrid.com/testing/integration-checklist.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.