Prevent duplicates
Use idempotency keys for safe retries without duplicate notifications.
Generate one idempotency key per logical submission:
const key = crypto.randomUUID()
Send it in the Idempotency-Key header, or in _idempotency_key for an HTML form. The key is scoped to the form and retained for the form’s retention period.
Replay behaviour
| Situation | Result |
|---|---|
| Same key, equivalent payload | 200, same submission_id, no new delivery |
| Same key, different payload | 409 idempotency_conflict |
| New key, same payload | New submission |
| Key after retention purge | May be reused as a new submission |
Equivalent payload means the same fields and values after control fields are removed and object keys are canonicalised. Field order does not matter. Turnstile and honeypot values are excluded from the digest.
Retry rules
- Reuse the key when retrying the unchanged payload.
- Rotate the key after success.
- Rotate the key when the user changes the data.
- Do not retry a
409; it means the content changed.
The key does not prevent a user from deliberately submitting the same enquiry twice with a new key. Postvia does not silently block legitimate repeat enquiries.