Glossary
What is idempotency?
An operation is idempotent when performing it more than once has the same effect as performing it once, which makes retries safe.
In integrations, an operation is idempotent if repeating it does not change the result after the first time. Creating “user 123 with these fields” twice should leave one user, not two. Idempotency matters because networks fail, webhooks are retried and jobs restart, so the same request will sometimes arrive more than once.
How does it work?
- Give each operation a stable key: an event ID, an idempotency key header, or a natural key such as an employee ID.
- Before applying a change, check whether that key was already processed.
- Prefer upserts (“create or update”) over blind inserts.
- Store the outcome, so a retry returns the same result instead of acting again.
A simple test: replay yesterday’s webhooks or rerun last night’s sync against a test environment. If the target ends up with exactly the same data as before, the integration is idempotent. If it creates duplicates or sends emails again, it is not.
Where it shows up in integrations
- Webhook handling Retried BambooHR or LMS webhooks must not create duplicate users or enrolments.
- Batch syncs A nightly sync that fails halfway can be rerun safely from the start.
- Payments and orders Payment APIs such as Stripe support idempotency keys to prevent double charges.
Common pitfalls
- Using auto-increment IDs as the only key, which cannot detect duplicates.
- Making “create” idempotent but forgetting side effects such as emails or enrolments.
- Storing processed keys for too short a time compared with the sender’s retry window.