Servers go down, deployments break things, certificates expire. Ezus Pay is built so that a temporary problem on your side doesn't make you lose events. This article explains what happens when a delivery fails, how to follow your deliveries, and how to fix the most frequent errors.
How a delivery works
For each event, Ezus Pay sends a POST request to your webhook's address and waits for the answer:
A
2xxcode within 8 seconds (200,201,204…): the event is delivered.Anything else (a
4xxor5xxcode, no answer within 8 seconds, a redirect, an unreachable server): the delivery failed and will be retried.
Your server should answer 200 as soon as it has received and verified the message, then do its processing in the background. To ignore an event you don't need, answer 200 as well: any other code makes Ezus Pay retry.
Automatic retries
A failed delivery is retried automatically, with growing intervals:
Attempt | If it fails, next attempt… |
1st | 30 seconds later |
2nd | 2 minutes later |
3rd | 10 minutes later |
4th | 1 hour later |
5th | 6 hours later |
6th | No more automatic attempts: the delivery is marked Failed |
In total, Ezus Pay keeps trying for about 7 hours 40 minutes. A short outage, such as a deployment or a server restart, is covered without you doing anything.
Each attempt sends the same event with the same id. If your server received it the first time but answered too late, it will get it again: store each id and ignore duplicates.
The delivery log
Every event sent to a webhook is kept for 30 days. Open the webhook's page (Settings → Integrations → Webhooks → click the webhook) to see its Delivery log:
Status | What it means |
Delivered | Your server accepted the event |
Retry scheduled | The last attempt failed; another is planned |
Pending | The event is being sent |
Failed | All attempts failed, or the webhook was suspended when the event occurred |
You can filter by status or by event. The Attempts column shows how many tries were made, and HTTP shows the last code your server answered.
Click a line to see its details: the exact content sent, your server's response, the error, the number of attempts and, for a delivery waiting to be retried, when the next attempt is planned.
Resend events
Once your server is fixed, you don't need to wait for the next automatic attempt:
Resend one event: click Resend on a failed line, or Resend this event in its details. It is sent right away.
Resend all failures: click Resend failures above the log. Every failed event from the last 7 days is sent again, progressively over the following minutes. Up to 500 events at a time.
A resent event keeps the same id. If your server had in fact already processed it, it will recognize it and can simply answer 200.
Resending is only available when the webhook is active.
When a webhook keeps failing
You're warned on screen
As soon as deliveries start failing, the webhook's status turns to Failing and a yellow banner appears on its page, stating since when.
You're warned by email
When an event has used up all its automatic attempts, every administrator of your agency receives an email: "Your webhook … is not responding", with a button to open the webhook. You receive at most one such email per webhook per day.
After 72 hours: the webhook is suspended
If a webhook hasn't accepted a single event for 72 hours, Ezus Pay suspends it rather than keep failing. Administrators receive a second email: "Your webhook … has been disabled", with the number of events waiting to be resent.
While it's suspended:
nothing is sent to your address;
events are still kept: they appear in the log as Failed, with the error "Endpoint disabled after repeated failures".
Once your server is fixed, open the webhook's page and click Re-enable and resend missed events in the red banner. The webhook is turned back on, and the events from the last 7 days are sent again.
Tip: before re-enabling, click Send a test to check your server is really back.
Suspended or disabled?
Suspended means Ezus Pay paused the webhook. Events are kept so you can catch up.
Disabled means you turned it off. Nothing is sent or kept.
Troubleshooting
Open the failed delivery's details and look at the HTTP response and the error:
What you see | Likely cause | What to do |
400 or 401 | Your server refused the signature: wrong secret, or body parsed before verification | See Verify that a webhook comes from Ezus Pay |
403 | The address is protected by a login, a firewall or an IP filter | Let requests reach this address. Rely on the signature for security |
404 | The address path is wrong | Check the URL in the webhook's Configuration |
405 | The address doesn't accept | Your server must accept |
301, 302, 307, 308 | The address redirects (to | Redirects aren't followed. Enter the final address |
429 | Your server limits the number of requests | Raise the limit for this address |
500 to 599 | An error inside your server | Check your server's logs. Ezus Pay keeps retrying |
Error mentioning aborted or a timeout | Your server took more than 8 seconds to answer | Answer |
No response, connection refused, address not found | Server offline, or domain name no longer pointing to it | Check the server is up and the domain resolves |
Error mentioning a certificate | Invalid, expired or self-signed SSL certificate | Install a valid certificate, e.g. a free Let's Encrypt one |
Error mentioning a non-public address | The domain now points to an internal network address | The address must be reachable from the internet |
Error messages in the log come straight from the network or your server, so they are in English.
Frequently asked questions
My server was down for an hour. Did I lose events?
No. The automatic retries cover about 7 h 40. Events will arrive once your server is back.
My server was down all weekend.
Events that used up their retries are marked Failed. After 72 hours, the webhook is suspended and new events are kept. Once you're back, click Re-enable and resend missed events (or Resend failures): everything from the last 7 days is sent again.
The outage lasted more than 7 days.
Older events can't be resent from the log. To catch up, your developer can list the payments of the period through the API (GET /transactions with a date range).
A payment went through, but my webhook received nothing.
Check that:
the webhook is subscribed to this event (Configuration);
it isn't Disabled;
the payment went through Ezus Pay: payments recorded by hand don't trigger any event;
the log shows a line for this event. If it's there with an error, the problem is on the receiving side.
The test works, but real events fail.
The test sends a small ping event. Real events carry more data and may trigger processing on your side: check that your server doesn't process the event before answering, and that it accepts every event type you subscribed to.
I received the same event twice.
That's expected: an event can be delivered again after a timeout or a resend. Both copies have the same id: process it once.
Does Ezus Pay send from fixed IP addresses?
Ezus Pay doesn't publish a list of IP addresses. To check that a message comes from Ezus Pay, verify its signature.