Skip to main content
Nuvion delivers event notifications to your server via HTTP POST whenever something significant happens: an account is created, a payment is received, or a transfer completes. Register a webhook endpoint to receive these events in real time rather than polling the API.

​
Webhook security

Each webhook endpoint has a unique secret Nuvion uses to sign every delivery, so you can verify events actually originate from Nuvion.
The secret is generated and displayed once, at creation. Copy and store it securely before leaving the page. If you lose access to it, rotate the secret instead of trying to recover the original value.

​
Rotating a webhook secret

Set rotate_secret: true when calling PATCH /entity-webhooks/:id to rotate a webhook’s secret. A new webhook secret is generated and displayed once, the same as at creation. After rotating a secret, update your webhook verification logic to use the new value.

​
Verifying webhook signatures

Nuvion signs every webhook request using HMAC-SHA256. Each request includes the following headers:

​
How signatures are generated

To generate the signature, Nuvion constructs the following payload:
Nuvion then computes:
The resulting hexadecimal digest is included in the x-nuvion-event-signature header.

​
How to verify a webhook

  1. Retrieve your webhook secret.
  2. Read the x-nuvion-event-timestamp header.
  3. Construct {timestamp}.{payload} using the webhook payload and timestamp.
  4. Generate an HMAC-SHA256 signature using your webhook secret.
  5. Compare the generated signature with the value in x-nuvion-event-signature.
  6. Process the webhook only if the signatures match.

​
Registering an endpoint

Register webhook endpoints with POST /entity-webhooks. You can register multiple endpoints per entity, each subscribing to a different set of events. See the Webhooks API reference for the full lifecycle, and the Nuvion Dashboard if you prefer to manage them there.
Use separate endpoints for sandbox and production. Sandbox events are sent to your sandbox webhook URL; production events go to your production URL.

​
Child entities

If a child entity doesn’t have its own webhook configured, events triggered on it are sent to its parent entity’s webhook instead. Register a webhook directly on a child entity to override this and receive its events separately. See Managing child entities for how the parent-child relationship works.

​
Delivery

Nuvion sends an HTTP POST request to your registered endpoint with a JSON body. Your endpoint must return a 2xx status code to acknowledge receipt. Any other response is treated as a failure and triggers a retry.

​
Request format

All payloads share the same top-level structure:

​
Retries

If your endpoint does not return 2xx, Nuvion retries up to 5 times with exponential backoff: 1, 2, 4, 8, then 16 minutes, a 31-minute total window. After the final attempt, the event is not redelivered.
Respond with 2xx immediately and process the event asynchronously. Slow handlers risk timeouts that trigger unnecessary retries.

​
Idempotency

Nuvion may deliver the same event more than once, for example if your server acknowledges receipt after a network timeout that already triggered a retry on Nuvion’s side. Your webhook handler must be idempotent. The recommended approach: store processed event IDs using the id field in the event data, and skip any event you have already handled.

​
Event types

See Event types for full payload schemas and examples for each event.

​
What’s next

Event types

Full payload schemas and examples for every event.

Webhooks API reference

Create, update, and manage webhook endpoints, plus delivery logs and test events.