# 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"
}
```


---

# Agent Instructions: 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://nivapay.gitbook.io/product-and-api-documentation/webhooks/overview.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.