Idempotency means the same technical request can be submitted safely multiple times without duplicating the business result. This is essential in e-commerce: webhooks are repeated, network connections fail and confirmation can be missing even though the first action was completed. Without idempotency, duplicate AFAS orders, repeated WooCommerce notes or even multiple refunds can result.
“We process every message only once” is not a realistic foundation. Design a process in which repetition is normal and traceable instead.
Why messages arrive twice
A system that receives no timely confirmation after sending cannot be certain the recipient completed the request. Retrying is then sensible. A webhook provider may also resend an event if the response was late. Administrators can additionally restart a failed task manually.
There are therefore two separate questions:
- Have we seen this technical message before?
- Has the desired business result already been achieved?
Answering only the first question is insufficient. A new event may refer to the same order again, while the result must exist only once.
Choose a stable identity
Use a key describing the business result, such as the combination of online store, order number and action type. For a refund, the intended amount or specific return action also belongs to the identity. The key must remain the same on repeated attempts and must not be randomly regenerated.
Also retain external references. If a WooCommerce order has already received an AFAS sales order number, the integration can check during recovery that the relationship still holds. A visible title or customer name is not a reliable key: it can change and is not necessarily unique.
Read before writing again
Suppose a request to AFAS or Mollie times out. Whether the action completed is unknown. Do not immediately resend the same mutation. First use the stable external identity to check whether the intended result already exists. If the outcome remains uncertain, refer the action to an employee rather than guessing.
This pattern is also called reconciliation: the integration compares the desired state with the demonstrable current state before deciding the next step. It takes more design work than a simple retry, but prevents financial and administrative harm.
Different actions need different protection
| Action | Risk on repetition | Appropriate protection |
|---|---|---|
| Create an AFAS order | Duplicate sales order | Check and retain the external order reference |
| Add a WooCommerce note | Cluttered order history and repeated email | Stable note identity or recognition of the existing outcome |
| Set stock to a value | Old value overwrites new value | Check version/order; write an absolute value |
| Issue a refund | Multiple movements of money | Unique refund request plus provider verification |
| Process delivery status | Reversion to an older status | Allowed status transitions and event order |
Prevent webhook echoes
Duplicate processing can also arise from a loop. Connect changes a WooCommerce order, WooCommerce publishes a new webhook event and that event starts the same action again. Mark the origin of changes or recognise the already processed state. Save only when something actually changes.
That final rule seems small, but matters. An unnecessary “save” can trigger new hooks, notifications and follow-up processes even if the content stayed the same.
Make retries visible and targeted
Administrators need more than a red error and a generic “retry” button. Show the intended business action, which external steps have succeeded and which step can safely run again. A multi-step return may already be recorded in AFAS while only the payment provider still needs checking.
Use a limit and increasing delay for automatic retries. Permanent input errors do not improve through endless repetition. Pause a task with an understandable recovery reason when mapping, permissions or source data needs changing.
Test uncertain outcomes in particular
- Send the same webhook event twice.
- Let the destination system succeed but lose the confirmation.
- Restart a task after one of several external steps is already complete.
- Process an older event after receiving a newer status.
- Let two workers pick up the same order simultaneously.
- Check that a manual retry retains the same action identity.
Idempotency is therefore a functional property of the whole process, not an isolated programming technique. In reliably integrating an online store and ERP we explain why traceability and recovery are fundamental. The specific AFAS context appears on WooCommerce–AFAS integration, while Yindle Connect makes the workflows involved manageable.
Frequently asked questions about safe retries
Is a webhook ID sufficient?
No. It may prevent exactly the same message from being processed twice, but two different messages can request the same business action. Use both message identity and a key for the intended result, such as “create AFAS order for shop X and order Y”.
Are status updates automatically idempotent?
Setting an absolute status to the same value seems safe, but associated side effects can still run twice. These include email, notes, stock changes or follow-up tasks. Check not only the field, but also whether the associated business action has demonstrably been completed.
How long should idempotency keys be retained?
Long enough to cover realistic retries, delayed events and manual recovery. For financial or administrative results, the external reference may form part of lasting process history. Align retention periods with business accountability and privacy; do not automatically retain complete payloads when a limited identity suffices.
Check protection in production
Monitor how often duplicates are blocked, how many actions need reconciliation after an uncertain outcome and which manual retries occur. A sudden increase may indicate timeouts, changed webhook settings or a key that is no longer stable. Make the signal investigable without widely exposing sensitive data in log entries.
For Mollie actions, the official documentation on idempotency keys is also relevant. Treat provider-specific protection as an additional layer while retaining your own business identity and result checks.
Want to check whether an existing integration safely handles duplicate business actions? Ask Yindle for a focused integration review.