Register webhook endpoint

Subscribe to transaction lifecycle events.

Sandbox APIhttps://sandbox-api.nuvante.io

Creates a webhook subscription. Whenever a transaction changes state, Nuvanté POSTs an event to the HTTPS URL you registered. Delivery is at least once, so deduplicate on Nuvante-Webhook-Id. You'll only see signingSecret when you create the subscription, so store it on your server like an API key. Deliveries are signed with HMAC-SHA256 over timestamp.body and have a five-minute replay window. Needs webhooks:manage.

Parameters

Register webhook endpoint parameters
Field	Type	Required	Description
Authorization	string · header	Yes	Bearer sandbox API key with `webhooks:manage`.
url	string (HTTPS URL) · body	Yes	Where we deliver events. It has to use HTTPS and resolve to a public address, so loopback and private IPs won't work.
events	("transaction.received" \| "transaction.in_flight" \| "transaction.settled" \| "transaction.cancelled" \| "transaction.parked" \| "transaction.failed")[] · body	Yes	The event types you want.
description	string · body	No	A label to help you recognise the subscription.

Responses

201Subscription created. This is the only time you'll see `signingSecret`.

Create a sandbox API key

Request

curl --request POST \
  --url 'https://sandbox-api.nuvante.io/api/v1/webhooks' \
  --header 'Authorization: Bearer nvt_sandbox_your_key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://hooks.partner-bank.test/nuvante",
  "events": [
    "transaction.settled",
    "transaction.parked",
    "transaction.cancelled"
  ],
  "description": "Production settlement listener"
}'

Response

{
  "data": {
    "id": "wh_523e4567-e89b-42d3-a456-426614174052",
    "url": "https://hooks.partner-bank.test/nuvante",
    "events": [
      "transaction.settled",
      "transaction.parked",
      "transaction.cancelled"
    ],
    "status": "active",
    "signingSecret": "whsec_…",
    "createdAt": "2026-09-01T10:00:00.000Z"
  },
  "meta": {
    "commandId": "123e4567-e89b-42d3-a456-426614174052"
  }
}