Webhooks
We use webhooks to notify you about changes that have occurred. To protect your server from unauthorized notifications we use JWS detached tokens - JSON Web Signature (RFC7515) - as you will read in the Verifying signed responses section. Please, refer to this section for more details about how JSON Web Signature works.
How to listen to webhooks
Notifications are sent as HTTP requests (webhooks) to an endpoint on your server.
The server configuration should be:
- Able to receive JSON messages over POST requests and read the notification object for the type of notifications for which you are listening.
- Support HTTPS traffic with TLSv1.2.
As optional, you might also need to add NomuPay's network to your firewall's allowlist.
Receive notifications
To ensure that your server is properly accepting notifications, we require you to acknowledge every notification of any type with a successful response (HTTP 2xx).
If we don't receive this response within 30 seconds, all notifications to your endpoint will be queued and retried.
Recommended steps:
- Verify the signature of the message.
- Acknowledge the notification with HTTP 2xx response.
- Handle the notification in your system, including handling duplicates.
Queued and retried notifications
If a 2xx HTTP status code is not received within 30 seconds or a status code other than 2xx is returned, we assume that the delivery was unsuccessful. We apply the following retry policy.
| Retry attempt | Time between attempts | Time since webhook event |
|---|---|---|
| 1 | 2m | 2m |
| 2 | 5m | 7m |
| 3 | 8m | 15m |
| 4 | 15m | 30m |
| 5 | 30m | 1h |
| 6 | 1h | 2h |
| 7 | 2h | 4h |
| 8 | 4h | 8h |
| 9-21 | 8h | 16h - 96h |
If the maximum number of retries is exceeded, the notification won't be retried.
Handle notifications
Handling webhook notifications correctly is crucial to ensure that your integration business logic works as expected.
Handle notifications asynchronously
We recommend handling notifications asynchronously in your system.
Duplicate notifications
In some cases, the client may receive the same notification twice, so clients should ensure that their system is able to handle duplicates. To deal with this they can use the unique notification identifier.
Order of notifications
Our webhooks system does not guarantee delivery of notifications in the order they are generated by our system.
Alternative tracking URL
Webhooks deliver status changes as they happen, meaning that you can get the update immediately instead of polling for status changes frequently. This makes webhooks much more efficient. Therefore, we recommend the use of webhooks for receiving, in real-time, payment status changes that occur in the background (like a consumer completing a payment in an alternative payment method platform).
If you are unable to consume webhooks, for operations that are pending, the
response includes a tracking URL (field trackingUrl) that you can use to poll
for status changes.
The tracking URL is the full URL but the domain. For example,
/v1/tracks/payments/MjdsSUM4N2x. Use the corresponding domain to poll for
status changes. For example, in the Live environment, you can use
https://api.nomupay.com, so the full URL would be
https://api.nomupay.com/v1/tracks/payments/MjdsSUM4N2x.
The response of the tracking URL has the same contract as the response of the original URL.