Webhook notifications allow you to efficiently track payments states, collections & receive events regarding your account
A webhook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately.
Unlike typical APIs where you would need to poll for data very frequently in order to get it real-time. This makes webhooks much more efficient for both parties.
Our webhook notifications allow you to efficiently track payments states, perform your reconciliation and proccess inbound payments.
They are push notifications sent as webhook message to URLs you define. We do not recommend using webhooks as a replacement for reconciliation purposes.
You can subscribe to several payment events. When one of these events is triggered, we send a HTTP POST request to a URL of your choice in a JSON format. Along with the event, data about the payment is included, which we refer to as the payload.
Supported events
These are the payment events for which you can subscribe to:
Event | Description |
|---|---|
payment_status | When a payment change its status and this status needs to be notified to customer |
accounts-entries | When an account gets an entry of CR or DR |
collection-status | When a Collection from universities changes its status |
When a Collection from universities changes its status
Setting up webhooks
To setup a webhook, you'll need the following to get started:
An API user with the permission to manage webhooks
A receiver which is a HTTPs URL / API endpoint that can receive binary streams(Content-Type as application/octet-stream) and HTTP POST in JSON format
A receiver which can handle payloads of up to 50mb
An encryption key of 32 characters, compatible with the 256-bit key required by the AES-256-GCM encryption algorithm
To have whitelisted PagoNxt IPs (see below)
Subscribing a callback URL for the Webhook
In order to trigger a webhokk call, the webhooks API needs to know which service to call and how.
Verb | Endpoint | Description |
|---|---|---|
GET | /subscriptions | List all active webhooks |
POST | /subscriptions | Subscribe to a Webhook event |
PUT | /subscription/{id} | Update existing information |
DELETE | /subscription/{id} | Remove a subscription to a webhook |
Replaying a missed webhook
It is possible to reuse a previously consumed payload on a webhook by calling POST /executions/replay-execution.
This resource uses the identification information of a previous webhook run to retrieve the payload that it sent that time and reuse it for the current callback. A new access token is negociated if required.
Webhook security
Consuming any API of PagoNxt requires to use OAuth2 and private JWT security. In the cases of Webhooks, the security model available is the following:
mTLS
Webhook signatures
So you have received your webhook request and the information contained within, but how can you be sure the information you received is correct?
Attackers can intercept a request and feed it with the wrong payload before it hits your endpoint. This way, even if the message is encrypted, it contains what they (the attackers) want you to see.
This provides another loophole for attackers to transmit corrupt information into your system.
One very effective way to verify that messages are legitimate is for both the webhook provider and client to perform signature verification on the messages.
The webhook provider sends a plain message along with a signature generated using the message and the HMAC cryptography algorithm to the client. When the client receives the message, it uses the HMAC algorithm and the message received to deduce its signature.
.png)
It then compares the deduced signature with that sent by the webhook provider. If the signatures match, the message is valid. If not, the message has been tampered with and should be rejected.
We will add a request header called X-Signature-SHA256 in the callback response of the webhook with the calculated hash. Consumer in his side can decide to check this signature for verifying that the message comes from PagoNxt Trade.
For calculating the signature we do a HMAC SHA256 hash of the body, we use a secret key of 72 characters, composed by the subscription Id (to the API) and a secret, who is called internally (environment variable) as webhooks-common-key
An example:
Secret Key Body HASH Generated
91179442-82f9-11ee-b962-0242ac120002pUGH8jnt5UL+hdGWm$d%Aj+%A%IshX$Lkc(*📘 Our standard security setup is TLS. If you wish to setup webhooks with mTLS, you have to contact your Integration Manager.