Troubleshoot webhook delivery failures
Webhook failures mean AtomicPay could not deliver an event to your endpoint, or your endpoint rejected it. This guide focuses on failed deliveries after you have already planned the integration in plan, test, and monitor webhooks.
Use it when logs show failures, when the simulator works but production does not, or when your external system never receives events that exist in Sales.
Failure patterns
| Symptom | Likely cause | First place to check |
|---|---|---|
| Logs show failed delivery | Endpoint returned an error or timed out | Webhook logs |
| Simulator works, production fails | Production payload, auth, or environment differs | Endpoint config and logs |
| No events received at all | Wrong URL, disabled webhook, or wrong events selected | Webhook settings |
| Duplicate actions in external system | Endpoint not idempotent on retries | Receiver application logic |
| Some events arrive, others do not | Event selection or triggering action missing | Selected events and Sales |
Investigation workflow
- Open the webhook in AtomicPay.
[Screenshot: Webhooks list — target webhook opened.]
- Confirm the endpoint URL is correct and publicly reachable.
[Screenshot: Webhook settings — endpoint URL visible and valid.]
- Check which events are selected against the workflow you expect. See webhook planning.
[Screenshot: Webhook events — subscribed events match workflow.]
- Review delivery logs for status code, attempts, and timestamps.
[Screenshot: Webhook delivery logs — failed attempts with status codes.]
- Run the simulator for the failing event type.
[Screenshot: Webhook simulator — test event sent.]
- Compare simulator success with the failed production attempt.
[Screenshot: Logs comparison — simulator success vs production failure.]
- Fix the external endpoint so it returns a success response quickly.
[Screenshot: External endpoint — returns 2xx success response.]
- Trigger a real test sale or subscription event when safe.
[Screenshot: Test sale triggered — webhook delivery retried.]
- Confirm the external system processed the event once, not multiple times.
[Screenshot: External system — single event processed, no duplicates.]
- If using Zapier or Make, verify the catch URL and automation step separately.
[Screenshot: Zapier or Make — catch URL and automation step verified.]
Endpoint checks
| Check | Why it matters |
|---|---|
Return 2xx quickly | Slow endpoints cause retries and duplicate risk. |
| Validate auth or signing | See secure webhook endpoints. |
| Queue heavy work | Do not block the HTTP response on long jobs. |
| Make handlers idempotent | Retries should not duplicate access or CRM updates. |
| Separate test and production endpoints | Prevents simulator success from masking production config errors. |
Common event-specific issues
| Event type | Also review |
|---|---|
| Purchase approved | Buyer access and delivery workflow |
| Purchase declined | Card declines or PIX failures |
| PIX generated | Incomplete payments |
| Cart abandoned | Recovery workflow |
| Refund or chargeback | Refunds and chargebacks |
| Subscription events | Subscriptions status and timing |
Best practices
- Start with the minimum events your automation needs.
- Test every production-critical event with the simulator before launch.
- Monitor logs after pricing, product, or endpoint changes.
- Keep payload reference in API documentation.
- Document retry behavior on your side before relying on webhooks for access provisioning.
Common mistakes
- Rebuilding the webhook without fixing the endpoint.
- Pointing production webhooks to a local or staging-only URL.
- Granting access on the wrong event, such as PIX generated instead of approved.
- Ignoring webhook security until after failures begin.
- Assuming missing webhook data means missing sales without checking missing data troubleshooting.
FAQ
Should I rebuild the webhook when logs show failures?
Usually not. Fix the endpoint or event handling first. Recreating the webhook without fixing the root cause often repeats the same failure.
Where is the full webhook setup guide?
See plan, test, and monitor webhooks for event selection, simulator use, and monitoring workflow.
Can Zapier or Make cause delivery failures?
Yes, if the catch URL, filter step, or downstream automation fails. Review Zapier or Make webhook patterns.
What evidence should I collect before escalation?
Webhook ID, event type, timestamp, endpoint response, sale ID when relevant, and screenshots from logs and your receiver system.