Integration best practices

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.