Overview

How to configure webhooks

To start receiving webhooks from Nexpay, follow these steps:

1. Create an HTTPS Endpoint on your server

Prepare an HTTPS endpoint capable of receiving POST requests. This endpoint must:

• Accept JSON payloads
• Be accessible from the public network
• Validate the webhook signature (explained in the signature verification section)
• Respond with HTTP status 200 OK to confirm successful delivery

2. Configure the endpoint in the client portal

• Log in to your Nexpay client portal and go to the webhook settings page
• Add your HTTPS endpoint URL
• After saving, the system will generate a public key, which you need to copy and later use to verify webhook signatures

Receiving webhooks

Webhooks are delivered as JSON-formatted HTTPS POST requests sent to your configured HTTPS endpoint.

Each webhook request contains:

• HTTP headers used for signature verification
• JSON body with structured event data

Your listener must respond with HTTP 200 OK to acknowledge successful receipt. Any other response will be considered a failure, and Nexpay will retry delivery according to a back-off schedule.

Headers

Every webhook request includes the following headers:

Body structure

Every webhook request body contains the following JSON fields:

Signature verification

To ensure that webhook requests are genuinely sent by Nexpay (and not a malicious third party), every webhook payload includes a signature in the X-Signature header that must be verified.

If the values do not match, the webhook should be rejected and logged. Do not process or acknowledge invalid signatures.

Signatures are generated using the ECDSA-SHA512 algorithm and NIST P-256 curve, and must be verified using the public key found in the client portal under webhook settings.

Error handling

If your endpoint fails to respond with HTTP status 200 OK in time, Nexpay will attempt to redeliver the webhook according to an exponential back-off scheduling algorithm.

Make sure:

• Your endpoint can handle bursts of retries
• You log and monitor errors
• You return 200 OK only after the event is fully processed

Examples

The data below contains an example of a request body, signature, and public key that can be used to test signature verification:

{
    "event": "payment.status",
    "payload": {
        "paymentId": 27,
        "feePaymentId": null,
        "externalPaymentId": null,
        "batchReference": null,
        "account": "LT953080020000000650",
        "amount": "5.01",
        "direction": "incoming",
        "status": "COMPLETED",
        "date": "2024-06-06",
        "networkType": "SEPA",
        "otherName": "Roach Combs LLC",
        "otherAccount": "LT093080020000000646",
        "details": "Test payment 501",
        "originalAmount": null,
        "originalCurrency": null,
        "runningBalance": "18.08"
    }
}

3045022026cfb1ace150acf7547db537e74772950bc03a96e14d50ae085a6853cc52b033022100ed30a1a50874622b0e74fe4874ed1b72d995d647ea3be135019a8ce2a8fcbe22

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEY3GPZkskfkKHCCysnSQEqgcQxs+W
oV3EubNu6uIb35QaIgFjatt+9go1ulcWRO9jdrDbKHzf+Jmb35q6yvimLA==
-----END PUBLIC KEY-----

Supported webhook event types