Overview

When an event related to an order occurs, Nivapay will send an HTTP callback to your system using the HTTP POST 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.

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 X-Nivapay-Webhook-Signature HTTP header.

For example, the header for the payload {"examplePayload":true} encrypted with the shared key my-shared-secret, looks like:

X-Nivapay-Webhook-Signature: bcdbb89e3031905f3cc1a20d16b5f969a17a7d8fa0c26e4a807c2193402d66f4

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:

Property	Type	Description
eventId	string (UUID v4)	Unique identifier for the event. Retries to the same events will share the same id.
timestamp	string (ISO-8601 timestamp)	Timestamp for when the event has occurred
eventName	string	Name of the event that occurred
context	json object (all params within this object are of type string)	Context for this event. Structure is defined by the event.

Example payload

{
  "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"
}