> For the complete documentation index, see [llms.txt](https://aliniex.gitbook.io/alix-pay/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aliniex.gitbook.io/alix-pay/api-reference/introduction/webhooks.md).

# 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](https://dashboard.alixpay.com/en/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](/alix-pay/resources/partner-dashboard/integration/webhooks-ipn_url.md) 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

```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](/alix-pay/api-reference/scan-to-pay-api/transactions/get-transaction-details.md) 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

```typescript
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**

```json
-----BEGIN PUBLIC KEY-----
MIIBITANBgkqhkiG9w0BAQEFAAOCAQ4AMIIBCQKCAQBKh0Ow2ADYAz8yXjNaez++
PZnyGmYx0enkvZlMbDgcSfO4Z7921Fx5NZ1k513nSI7rP9Lgp1weKQwnaDrALHaj
HGCzTThC70ElW9eO3QVhAQ930dflhz0k9xsIrdFpqlFFQTRGZ8Ylzj+2rlBWYAsN
OegW8BQq7JLRNQX9Fi55ENpNVxwQsNKtLRdzKYAlJ3G0W7R0po5lh4DxuFnQ/ngE
ARKvI8y4cty4mXi7j+pS3AJekmZwMefzyLCY97T/pWdqVOVzOl7BhUNynQfZvHcG
rt6faSAMbK4mvljfxoAkEIsxL5t2xzR+AWHBeeF0GdGHCdpyfKUyJm8oq1FIuqZZ
AgMBAAE=
-----END PUBLIC KEY-----
```

**Production**

```json
-----BEGIN PUBLIC KEY-----
MIIBITANBgkqhkiG9w0BAQEFAAOCAQ4AMIIBCQKCAQB1KCqLRzqeRMpOh//gll08
/Xmoh1r8suUszvC3H1dG2mz/cEos3jG0AI+67ba5D1bSpIJCfOaHCPNAFqZiKaSR
X9QiWlnTqgyt45MUS5dZtRE4DA/pmzHa2NEW0yXeheycSbT4Yurw804ofB4wTVwk
PEF0+9bdBB544ZGxZegiGC9NQTrfqLiCO8fCHWsPbKYix97k0gfFl0NHhX+UB1pL
g5MPVk255mr7+63ymgc42ryhtx0f+aZALISdl/tfH7f35h4dE7kPJlGv6e7bgKVA
HIFB9sfcWUs70/Cpa5rN0u4P14NHRZWHY/Lhv3uJEm6owr1WKA3nAQTHKdshcFar
AgMBAAE=
-----END PUBLIC KEY-----
```

### 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](/alix-pay/resources/order-status.md)<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://aliniex.gitbook.io/alix-pay/api-reference/introduction/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.