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.
Registering an endpoint
Register your webhook URL in the Nuvion Dashboard. Nuvion sends all enabled events to a single endpoint URL per environment.
Use separate endpoints for sandbox and production. Sandbox events are sent to your sandbox webhook URL; production events go to your production URL.
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.
POST https://your-server.example.com/webhooks
Content-Type: application/json
{
"event": "inflows.completed",
"data": { ... }
}
| Field | Type | Description |
|---|
event | string | The event type. e.g. inflows.completed |
data | object | Event-specific payload. Shape varies by event type — see Event types. |
Retries
If your endpoint does not return 2xx, Nuvion retries delivery with exponential backoff for up to 15 minutes. After the retry window expires, 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
| Event | Trigger |
|---|
accounts.created | A new account is created for an entity |
account_details.created | Bank account number or wallet address is generated |
account_details.updated | Account details are updated (status change, new metadata) |
inflows.completed | A payment is received into an account |
outflows.created | A transfer request is received and queued for processing |
outflows.completed | A transfer completes successfully |
outflows.failed | A transfer fails |
outflows.cancelled | A transfer is cancelled before completion |
