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

# Overview

When an event related to an order occurs, Nivapay will send an HTTP callback to your system using the HTTP <mark style="color:purple;">`POST`</mark> verb.

To start receiving callbacks, you must provide the following to Nivapay support via a secure channel, before integrating with the APIs:

* Webhook URL to callback to
* Shared secret in a UUID v4 format used to authenticate callbacks from Nivapay.\
  In order to generate a shared secret, you can use the following [UUID generator](https://www.uuidgenerator.net/version4).

### Webhook Signature

All webhooks sent from Nivapay are signed with a shared secret that is known only by you and Nivapay. This ensures the integrity of the data contained in the webhook and also proves that Nivapay is the sender of the webhook.

Specifically, the signature uses HMAC-SHA256, using the shared secret as the key and the full HTTP request body (UTF-8 encoded) as the message. The resulting signature is provided in lowercase hexadecimal format in the <mark style="color:purple;">`X-Nivapay-Webhook-Signature`</mark> HTTP header.

For example, the header for the payload <mark style="color:purple;">`{"examplePayload":true}`</mark> encrypted with the shared key <mark style="color:purple;">`my-shared-secret`</mark>, looks like:

<mark style="color:purple;">`X-Nivapay-Webhook-Signature: bcdbb89e3031905f3cc1a20d16b5f969a17a7d8fa0c26e4a807c2193402d66f4`</mark>

Never consume the payload before validating the signature.

### Webhook Structure

All webhooks are sent as JSON objects, and share the same general structure as described in the following table:

<table><thead><tr><th width="164.33333333333331">Property</th><th width="275">Type</th><th>Description</th></tr></thead><tbody><tr><td>eventId</td><td>string (UUID v4)</td><td>Unique identifier for the event. Retries to the same events will share the same id.</td></tr><tr><td>timestamp</td><td>string (ISO-8601 timestamp)</td><td>Timestamp for when the event has occurred</td></tr><tr><td>eventName</td><td>string</td><td>Name of the event that occurred</td></tr><tr><td>context</td><td><p>json object</p><p>(all params within this object are of type string)</p></td><td>Context for this event. Structure is defined by the <code>event</code>.</td></tr></tbody></table>

#### Example payload

```json
{
  "eventId": "aeb7475b-39c4-41ae-8237-d74a7379c355",
  "timestamp": "2023-04-01T12:47:02.147Z",
  "eventName": "order.onramp.processing",
  "context": {
    "orderId": "VKP3OBZ3XG",
    "userRef": "1xdeavy",
    "merchantOrderRef": "3589cb4a-0830-497d-a92d-c5178eb2ab9f",
    "fiatSymbol": "GBP",
    "fiatAmount": "50",
    "virtualAssetSymbol": "ETH",
    "virtualAssetNetwork": "Ethereum",
    "virtualAssetAmount": "0.028693"
}
```