Webhooks

Webhooks are HTTP callbacks that deliver real-time notifications to your server when events occur in your division.

How webhooks work #

When an event occurs (e.g., a seller’s KYC status changes), Nuvei for Platforms sends an HTTP POST request to your configured webhook URL. The request body contains a JSON payload with details about the event.

Authentication #

All webhook requests are signed using HMAC-SHA512 to ensure authenticity. Each request includes the following headers:

Verifying the signature #

To verify the authenticity of a webhook request:

1. Construct the data string using the format:

   {webhookUrl}:{accountOwnerCode}:{timestamp}
   

   Where:

   • webhookUrl is your configured webhook endpoint
   • accountOwnerCode is extracted from the request body
   • timestamp is the value of the x-timestamp header

2. Compute the HMAC-SHA512 signature using your API access token as the secret key.

3. Base64-encode the computed signature.

4. Compare the computed signature with the value in the x-signature header.

Verification example #

Given:

• API key: my_super_secret_key
• Webhook URL: http://my-service.com/api
• x-timestamp: 2023-08-21T10:56:59.849101Z
• Body: {"accountOwnerCode": "test account code", "payoutStatus": "REJECTED", ...}

The data string would be:

http://my-service.com/api:test account code:2023-08-21T10:56:59.849101Z

The expected x-signature value:

tMtbhpFv/FIZqrkD75M97wrCLM2Vl381Ou+3UObpYANw8jrZGHUQxuR/2EWcx/ycZAalT4MjtXua1+EdEAgucg==

KYC Status Update #

Sent when a seller’s KYC status changes. The webhook contains information about the status change, whether new KYC data is needed, and a hosted onboarding link that can be shared with the seller to collect the necessary data.

Possible statuses:

Sample payload:

{
  "accountOwnerCode": "FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc",
  "kycStatus": "MISSING_DATA",
  "kycMessage": "Missing data for the following fields: address.city, phone, registrationNumber, ubos.address.country, ubos.lastName, address.houseNumber, address.street, ubos.firstName",
  "hostedOnboardingUrl": "https://onboarding.payaut.com?token=eyJhb..."
}

Payout Status Update #

Sent when the status of a payout request changes.

Possible statuses:

Sample payload:

{
  "accountOwnerCode": "FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc",
  "payoutStatus": "PROCESSED",
  "payoutCode": "FD5CMdGdJD7gUGVfTtDUU77vYtUSaa37tJ7",
  "payoutMessage": "Payout was requested."
}

Transaction Status Update #

Sent when a transaction status changes during the reconciliation process.

Possible statuses:

Transaction types: PAYMENT, REFUND

Sample payload:

{
  "originalEventTime": "2024-06-15T10:20:30.638627Z",
  "virtualAccountCodes": [
    "FD5CKXQSMQWnvyP8CQqgjceVLJGbr1Y2DzG"
  ],
  "splitCode": "FD5CKXSctdwrzkUUQCTWGXzKkQDqxRDnq4C",
  "extRef": "order-12345",
  "pspExtRef": "pspExtRef_123",
  "pspMutationExtRef": "pspMutationExtRef_123",
  "type": "PAYMENT",
  "status": "RECONCILED"
}