# Integration checklist

> Check your integration's versioning, errors, retries, webhooks, credentials and safety before you send real traffic.

Use this checklist after your integration works with test numbers and before
it sends real traffic. Each item links to the page with the full rules.

## Requests

**Pin the API version.** Send `Polymorfa-Version: 2026-09-22` on every
Messaging and Platform request, so a new contract date doesn't change your
integration without warning. Read the version the response echoes. See
[Versioning](https://docs.polymorfa.com/api/versioning).

**Handle every error.** Branch on the error `code`, not the message text. Treat
`401` and `403` as configuration problems and `404` on another project's
resource as a boundary, not a reason to retry. Log the request ID. See
[Errors](https://docs.polymorfa.com/api/errors) and, in TypeScript, [SDK errors](https://docs.polymorfa.com/development/error-handling#handle-errors-in-code).

**Retry writes with an idempotency key.** Send an `Idempotency-Key` with every
message write you might retry, and reuse the same key for the retry. Platform
webhook changes require one. A key never makes a changed request safe. See
[Idempotent requests](https://docs.polymorfa.com/development/idempotency).

**Respect rate limits.** Back off on `429` and follow `Retry-After`. See
[Rate limits](https://docs.polymorfa.com/api/rate-limits).

## Webhooks

**Register endpoints for each project.** Subscribe to the event types you
handle, in the project that owns the Numbers. Team endpoints receive only team
events. See [Webhooks](https://docs.polymorfa.com/development/webhooks).

**Verify every signature.** Check `X-Webhook-Signature` against the raw request
body before you parse it, and reject a mismatch. See
[Verify a webhook](https://docs.polymorfa.com/development/webhooks#verify-a-webhook).

**Handle duplicates and order.** Store each event `id` and skip repeats. Expect
retries and events that arrive out of order. Return `2xx` only after you have
stored the event. See [Receiver rules](https://docs.polymorfa.com/development/webhooks#receiver-rules).

## Credentials

**Keep keys on your servers.** Team keys and project tokens belong in a secret
manager or server environment, never in browser or mobile code. Give browsers
and apps a [client token](https://docs.polymorfa.com/development/client-tokens) instead.

**Use the narrowest credential.** Prefer a project token over a team key, and
select only the permissions the integration uses. See
[API keys](https://docs.polymorfa.com/development/api-keys).

**Plan rotation.** Deploy a replacement before you revoke a credential, and
revoke any credential that may have been exposed. See
[Rotate a key](https://docs.polymorfa.com/development/api-keys#rotate-a-key).

## Numbers and safety

**Replace test numbers with real numbers.** Test numbers reach only other test
numbers in the same project. Connect real numbers with
[QuickLink](https://docs.polymorfa.com/numbers/quicklink) and choose each Number's tier. See
[Number tiers](https://docs.polymorfa.com/billing/number-tiers).

**Protect new real numbers.** Turn on the [warm-up plan](https://docs.polymorfa.com/safety/warm-up-plan)
for the project and review [Safe Mode](https://docs.polymorfa.com/safety/safe-mode) before you send at
volume. See [Safety](https://docs.polymorfa.com/safety).

**Honor opt-outs.** Keep your team's opt-out list current and don't message
numbers on it. See [Opt-outs](https://docs.polymorfa.com/campaigns/opt-outs).

## Billing

**Upgrade to Pay-As-You-Go when you need more than Free.** Free teams have one
project and one real Number at no charge, and can't send QuickLinks for real
numbers. See [Upgrade to Pay-As-You-Go](https://docs.polymorfa.com/billing/upgrade).

**Set spending limits.** Give projects, Customers and Numbers monthly limits in
credits, so a fault in your integration can't spend the whole balance. See [Spending budgets](https://docs.polymorfa.com/billing/spending-budgets)
and [Usage](https://docs.polymorfa.com/billing/usage#monthly-spending-limits).

## See also

- [How Polymorfa works](https://docs.polymorfa.com/get-started/how-polymorfa-works)
- [Testing](https://docs.polymorfa.com/testing)
- [Logs](https://docs.polymorfa.com/development/logs)
