Use Idempotency-Key headers with the Pinned Events API to safely retry event creation requests without creating duplicate event listings.
What idempotency means
Idempotency lets a client retry the same create-event operation safely. The same Idempotency-Key with the same canonical payload returns the cached successful response instead of creating another event.
When to use Idempotency-Key
Use Idempotency-Key on create-event requests from webhooks, scheduled imports, queues, or any automation that may retry after a timeout or network failure.
Recommended key format
cms-post-123-create
crm-event-456-publish
partner-form-789-create
nightly-import-2026-06-12-row-42Same key and same payload
When the same Idempotency-Key is retried with the same canonical payload after a successful create request, the API replays the cached success response instead of creating another event.
Same key and different payload
If the same Idempotency-Key is reused with a different payload, the API returns a conflict. Generate keys from stable source IDs and actions, not from timestamps created during retry.
Duplicate prevention
Duplicate prevention depends on sending the same stable key for the same source event and action. Do not generate a new random idempotency key for each retry of the same source event.
Retention duration
Succeeded idempotency entries are retained for the configured Public API idempotency window. The default succeeded-entry TTL is 15 minutes, and in-progress entries use a shorter default TTL of 45 seconds.