# Integration best practices

> The habits that make an integration safe, frugal and robust against errors.

## Security

- Store tokens and webhook secrets in a secret manager, never in code. A committed token is recognised by its `nf_` prefix: revoke it at once.
- One token per integration, with only the scopes it needs. Revoking one does not cut the others.
- Verify the signature of every webhook, on the raw body, in constant time.

## Safe writes

- Send an `Idempotency-Key` on every creation, and the same key when you retry.
- Retry `5xx` and `429` with an increasing delay; never retry a `401`, a `403` or a `422` without changing anything.

## Saving rate

- Subscribe a webhook rather than polling; if you poll, space the calls and respect `Retry-After`.
- Send back the `ETag` you received in `If-None-Match`: a `304` response costs nothing.
- Read the issue summary before paginating their occurrences.

## Reading figures honestly

- `null` means "not measured", never zero. An average travels with its denominator: read it.
- A truncated or blocked crawl (`comparable: false`) does not compare.
- Rely on `code`, never on `title`, which is translated.