Every POST that creates something sends an Idempotency-Key, generated once per object and reused only to retry that same request.
Webhook signatures are verified, and a delivery whose t is more than 5 minutes from your clock is rejected. An old created_at is never a reason to reject an event.
Your webhook handler stores each event, deduplicated by id, before it returns 2xx, and processes it in the background.
You ignore events that would move a record backwards.
Someone on your side checks each paper’s warnings and approves it, or your code approves it deliberately.
You handle every outcome: paper awaiting_review, ready and failed; submission graded (including no_readable_answers), released, failed and canceled.
A resent batch treats 409 submission_exists as already done, using resource_id.
You handle 402, 429 (waiting for Retry-After) and 5xx (retrying with backoff).
You can catch up on missed events with GET /v1/events.
You store our IDs (pap_…, sub_…) against your own records.
You act on credits.balance_low and credits.expiring before credits run out.
Keys live in a secrets manager, never reach a browser, an app or your logs, and your team knows how to revoke one.
You’ve run the whole flow in test mode, including a review link and each simulated outcome.
