> For the complete documentation index, see [llms.txt](https://docs.neox.vn/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neox.vn/docs/global/global-collections/integration/event-notification.md).

# Event Notification

Global Collections is an **event-driven** service. Many operations complete asynchronously — virtual account approval, incoming funds, payout results, refund and sub-merchant status changes are all delivered to the Merchant as **webhooks**.

This page explains how to configure and verify webhooks. The payload of each event type is documented in its own webhook page (linked below).

## Configuration

Configure webhooks on the Merchant Portal under the **Global Collections service** menu.

#### Parameters description

* **URL:** The endpoint on the Merchant system that receives webhook `POST` requests.
* **Secret key:** Used to verify the `secureHash` of each payload.
* **Authorization type:** `No Auth` or `Basic Auth`.
* **Type:** The event type(s) this URL subscribes to — see the catalogue below.

A Merchant may register multiple URLs, each subscribing to a different set of event types.

## Delivery

* NeoX sends an HTTP `POST` request to the configured URL whenever a subscribed event occurs.
* The request body is `application/json`.
* The Merchant endpoint must respond with **HTTP 200** to acknowledge receipt.
* If the endpoint does not acknowledge, NeoX **retries** the delivery with a backoff schedule. Webhook handlers must therefore be **idempotent** — the same event may be delivered more than once. De-duplicate on the event's primary identifier (e.g. `requestId`, `transId`, `collectionOrderId`).

## Verifying `secureHash`

Every webhook payload includes a `secureHash` field. To verify it:

1. Take all payload fields **except** `secureHash` (and except optional fields, where the webhook page says so).
2. Sort the keys in alphabetical order and concatenate their values.
3. Append the **Secret Key** configured on the Merchant Portal.
4. Compute the `SHA256` hash and Base64-encode it.
5. Compare the result with the received `secureHash`. Reject the payload if they differ.

## Event catalogue

| # | Type              | Triggered when                                             | Payload reference                                                                                |
| - | ----------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| 1 | `VIRTUAL_ACCOUNT` | A virtual account application is approved / opened.        | [Virtual Account Webhook](/docs/global/global-collections/virtual-account-management/webhook.md) |
| 2 | `COLLECTION`      | Funds arrive in a virtual account (incoming collection).   | [Collection Webhook](/docs/global/global-collections/collection-management/webhook.md)           |
| 3 | `REFUND`          | A refund request changes status.                           | [Refund Request Webhook](/docs/global/global-collections/refund-request-management/webhook.md)   |
| 4 | `PAYOUT`          | A payout / remitout request changes status.                | [Payout Request Webhook](/docs/global/global-collections/payout-request-management/webhook.md)   |
| 5 | `SUB_MERCHANT`    | A sub-merchant onboarding or qualification status changes. | [Sub-Merchant Webhook](/docs/global/global-collections/sub-merchant-management/webhook.md)       |


---

# 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://docs.neox.vn/docs/global/global-collections/integration/event-notification.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.