Webhooks

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:

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.

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.

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:

91179442-82f9-11ee-b962-0242ac120002pUGH8jnt5UL+hdGWm$d%Aj+%A%IshX$Lkc(*

{
    "type": "payment-status",
    "entityId": "a1726272A",
    "payload": {
        "status": "ACCC",
        "pacs002": {
            "FIToFIPmtStsRpt": {
                "GrpHdr": {
                    "MsgId": "PNXiFDnowTcs01O80080266354238767104",
                    "CreDtTm": "2023-08-10T11:47:25.454Z"
                },
                "TxInfAndSts": [
                    {
                        "OrgnlGrpInf": {
                            "OrgnlMsgId": "CBRL25916473EUR_EMI_DEV",
                            "OrgnlMsgNmId": "pacs.008.001.08"
                        },
                        "OrgnlInstrId": "CPF75830613EUR_EMI_DEV",
                        "OrgnlUETR": "4a9dc62f-9a7b-4bb5-96d9-24b7f501a1bc",
                        "TxSts": "ACCC",
                        "InstgAgt": {
                            "FinInstnId": {
                                "BICFI": "PAGOES20"
                            }
                        },
                        "InstdAgt": {
                            "FinInstnId": {
                                "BICFI": "CLIENT BIC"
                            }
                        }
                    }
                ]
            }
        }
    }
}

f28ab65aaa79636da98b5f061e2e9a8446ae57830146254a38a0e8b8624eb04a

Webhook signatures. This will be enabled in any security models, but is also a security model by itself. See Webhook signatures

📘

Our standard security setup is TLS. If you wish to setup webhooks with mTLS, you have to contact your Integration Manager.