A webhook is an address (a URL) on one of your tools. Each time something happens in Ezus Pay, such as a payment received or a refund issued, Ezus Pay sends a message to that address within seconds.
To understand when to use a webhook rather than the API, see What can you build with the API and webhooks?.
Only administrators can set up webhooks.
Before you start
You need an address that can receive the messages. Depending on your setup:
Your developer gives you a URL on your own server, e.g.
https://erp.youragency.com/webhooks/ezus-pay.A no-code tool such as Zapier or Make gives you a URL when you create a scenario that starts with a webhook trigger.
Just want to see what a webhook looks like? Free services such as webhook.site give you a temporary address and show every message it receives. It's a good way to explore before involving anyone.
The address must:
start with
https://be reachable from the internet (internal or private network addresses are refused)
use the standard port (no
:8443or similar at the end)be the final address: redirects are not followed
Add a webhook
Go to Settings → Integrations.
In the Webhooks block, under your API keys, click Add a webhook.
Fill in the form:
Endpoint URL: the address your developer or tool gave you.
Name (optional): what this webhook is for, e.g. ERP or Accounting. It's how you'll recognize it in the list and in alert emails.
Events to receive: tick the events this tool needs, or Select all. Each event comes with a short description. They are detailed in Webhook events explained.
Click Add.
If the address is refused, the reason appears under the field:
"This address is not allowed": it's not public, not HTTPS, or uses a non-standard port.
"Address not found": the domain name doesn't exist. Check for a typo.
Copy the signing secret
As soon as the webhook is created, Ezus Pay shows its signing secret, a code starting with ezpw_whk_. Your developer uses it to check that each message really comes from Ezus Pay (see Verify that a webhook comes from Ezus Pay).
Copy it and give it to whoever builds the connection. It is shown only once. If you lose it, you can generate a new one from the webhook's page.
Click I have copied the secret to close the window. No-code tools such as Zapier don't need the secret; you can simply close the window.
Send a test
Your webhook now appears in the list. Click it to open its page, then click Send a test.
Ezus Pay immediately sends a test message to your address and shows how it answered:
Green: "Your server answered 200 in 142 ms". Everything works.
Red, with a code: your address answered, but with an error. Only a 2xx code counts as a success.
Red, "No response from your server": the address couldn't be reached. Check it's online and public.
The test message is a special ping event. It isn't recorded in the delivery log and doesn't affect the webhook's status, so you can send as many as you like.
Read the status of your webhooks
Each webhook shows a status in the list and on its page:
Status | What it means |
Waiting | Nothing has been sent yet. It will switch as soon as a first event occurs |
Operational | The last messages were received |
Failing | Recent messages were refused or unanswered. Ezus Pay keeps retrying |
Suspended | Paused by Ezus Pay after 72 hours without a single success. Missed events are kept |
Disabled | You turned it off. Nothing is sent or kept |
What happens when a webhook fails, and how to catch up, is covered in Deliveries, retries and troubleshooting.
Change a webhook
On the webhook's page, the Configuration section lets you change the URL, the name and the events. Click Save to apply. A new URL goes through the same checks as when you created the webhook. The changes apply to the next events.
Disable or delete a webhook
Disable (button at the top of the webhook's page): no events are sent or kept while it's disabled. Click Re-enable to turn it back on. Use this for a planned maintenance on your side.
Delete (bin icon): the webhook disappears for good and no more events are sent to its address.
Good to know
Up to 5 webhooks per agency. Each has its own address, its own events and its own secret. You can send the same events to several tools.
Your tool must answer quickly, within 8 seconds, with a 2xx code. Your developer should acknowledge the message first, then process it.
Every message is logged. The webhook's page lists everything sent over the last 30 days, with what your tool answered.