Webhooks

We have deployed a digital signature for our webhooks. Here are some information on how it will be signed and how you can verify the body with the digital signature. Once your Webhook is connected to AliX Pay, you will start receiving notifications from Alix Pay. All events will be sent with the following headers (the public key for verifying the signature will be provided by Alix Pay):

Before you begin

Log into AliX Pay Dashboard and configure your webhook URL's which AliX Pay will use to send your webhooks. You will be able to configure separate webhook URLs for both Sandbox and Production environments.
Otherwise feel free to contact your Account Manager with your Webhook URLs.
You also can access document for webhooks's configration for more details

Using Webhooks

After we have configured your webhook URLs, webhooks will be sent to this URL when an order has changed status. A webhook notification will be sent via HTTP POST in the below format:

json

{
  "externalOrderId": "string",
  "type": "string",
  "fiatAmount": 0,
  "paidAmount": 0,
  "tokenTransfer": {
    "currency": "string",
    "network": "string",
    "price": 0,
    "amount": 0,
    "address": "string",
    "txHash": "string"
  },
  "bankTransfer": {
    "bankAccountName": "string",
    "bankAccountNumber": "string",
    "bankName": "string",
    "contentPayment": "string",
    "totalPayment": 0,
    "qrUrl": "string"
  },
  "fees": {
    "systemFee": 0,
    "processingFee": 0
  },
  "status": "string", // AWAITING_PAYMENT | PAYMENT_COMPLETED | PROCESSING_TOKEN_TRANSFER | SUCCESS | FAILED 
  "description": "string",
  "createdAt": "string",
  "expiresAt": "string",
  "signature": "string"
}

When you receive a webhook, you can then call the Get Order Details endpoint to retrieve detailed order information. This ensures that you do not receive calls from bad actors with incorrect information.

Securing Webhooks

Your webhooks will be sent with SHA256withRSA signature. SHA256withRSA guarantees that the message is from Alix Pay and has not been altered on the way by a third party.

You can request an WebhookSecretKey and Secret from your Account Manager.

You will receive the webhook with an signature with hash format that is generated in the following format:

"externalOrderId|type|fiatAmount|status|secretKey"

In order to decode the encryption, you will need to run the hash operation by computing the SHA256withRSA hash function, and then perform an equality match.

We append the timestamp to the body before hashing and signing it to prevent replay attacks. You can verify the signature with the publicKey provided by AliX Pay. Here is the sample code to verify the signature in Node.js

const crypto = require('crypto');

// Reap-Signature: `timestamp=123456;signature=abcdefg`
let verifier = crypto.createVerify('RSA-SHA3-256');
const publicKey = '';
verifier.update(
  JSON.stringify({...body, timestamp: 123456 })
);
const result = verifier.verify(
  publicKey,
  'abcdefg',
  'base64'
);
console.log(result); // true means the signature is valid

// it's also recommended to check the timestamp to prevent replay attacks

Please see the public keys below:

Sandbox

Production

Webhook Events

A webhook will be triggered and sent to your URL on all Order status transitions. The full list of order statuses can be found here

PreviousEnvironment NextScan To Pay API

Last updated 1 year ago