Testing Webhooks
When a customer pays a reference, IZI Pay notifies your application with a webhook. The IZI Pay CLI lets you trigger that webhook in the sandbox whenever you want, so you can check that your application handles it correctly.
How it works
izipay ppr pay(orizipay ppr test) tells the sandbox that a customer paid the reference.- The sandbox processes it like a real MULTICAIXA payment: the reference becomes
Paidand a payment is recorded. - A few seconds later, the sandbox sends the webhook to your application, the same way production does.
izipay webhooks statusshows each delivery attempt and whether your application accepted it.
Where the webhook goes
| You ran | The webhook goes to |
|---|---|
ppr pay or ppr test with --callback-url <url> | That address, for this payment only |
Without --callback-url | The payment reference webhook saved for your sandbox merchant, if IZI Pay set one up for you |
Without --callback-url, and no saved webhook | Nowhere. The payment still succeeds and the CLI says no webhook was sent. |
The address must be reachable from the internet. The sandbox refuses private and local network addresses such as localhost, 127.0.0.1, 10.x.x.x or 192.168.x.x.
What your application receives
A POST request with a JSON body and an Access-Key header, in the same format as production. The fields and their meaning are described in Merchant Webhooks.
http
json
In the sandbox, entidade carries your entity, and nib and banco are always "Inexistente" because there is no real bank account behind the payment.
The Access-Key header. With --access-key, the sandbox sends the value you chose. Without it, the sandbox generates one (it starts with sbx_) and the CLI shows it. Use it to test that your application rejects requests with a wrong key.
What your application must answer
Answer HTTP 2xx with a JSON body that contains "Success": true:
json
Only Success is checked; Obs and Id are optional. Anything else counts as a failed attempt:
- an HTTP status other than
2xx, such as404,405or500; - an empty body, plain text or HTML, even with status
200; - invalid JSON, such as a missing comma;
"Success": false.
Retries
A failed attempt is retried automatically, with growing waits between attempts: about 15 seconds, then 30 seconds, 1 minute, 2 minutes and so on, up to 1 hour. That's up to 10 attempts over about 2 hours.
Retries continue after the CLI finishes. If ppr test fails because your application rejected the webhook, your application keeps receiving the same webhook until it answers "Success": true or the attempts run out. Use the Id field to recognise a webhook you have already processed.
Testing an application on your own computer
The sandbox can't reach localhost. To test an application running on your computer, either:
- expose it through a tunnel service, such as ngrok or Cloudflare Tunnel, and pass the public address it gives you as
--callback-url; or - first look at the webhook in a request inspector such as webhook.site. Set its response to the JSON above, with content type
application/json. Otherwise every attempt counts as failed.
Troubleshooting
| What you see | Likely cause |
|---|---|
Webhook not sent after ppr pay | No --callback-url was given and your merchant has no saved webhook. |
No webhook attempt yet | The first attempt usually arrives within 5 to 10 seconds. Add --wait. |
HTTP 200 rejected: ... missing/invalid Success | Your application answered 200, but the body didn't contain "Success": true. |
HTTP 404 or HTTP 405 | The address is wrong, or your application doesn't accept POST there. |
no answer | Your application didn't answer within 10 seconds, or couldn't be reached. |
INVALID_CALLBACK_URL | The address isn't public. See Where the webhook goes. |
izipay ppr test --amount 1000 --callback-url <your address> is the quickest way to check everything at once. Run it again after each change to your webhook handler.