Webhooks let you subscribe to Nuvion events and receive HTTP POST notifications when those events occur. Each webhook is scoped to the authenticated entity and can subscribe to specific event types or all events.
The Webhook object Unique webhook identifier.
The ID of the entity this webhook belongs to. Derived from the API key used to create it — not set directly.
The HTTPS endpoint Nuvion delivers events to. Must use the https protocol.
Duration in seconds until the webhook expires. After expiry, no further events are delivered and the webhook status becomes inactive.
The set of events this webhook is subscribed to. Show enabled_events fields
When true, subscribes to every event type. Overrides all other selections in this object.
Account lifecycle events. Fires when a new account is created.
Fires when an account is updated.
Fires when an account is deleted.
Account details lifecycle events (bank account numbers, wallet addresses). Show account_details fields
Fires when account details are created.
Fires when account details are updated.
Fires when account details are deleted.
Incoming payment events. Fires when an inflow is initiated.
Fires when an inflow settles successfully.
Fires when an inflow fails.
Fires when an inflow is cancelled.
Fires when an inflow is refunded.
Outgoing payment events. Fires when an outflow is initiated.
Fires when an outflow settles successfully.
Fires when an outflow fails.
Fires when an outflow is cancelled.
Fires when an outflow is refunded.
Funding session events. Show funding_sessions fields
Fires when a funding session is updated.
Payment intent events. Show payment_intent fields
Fires when a payment intent is completed.
Fires when a payment intent fails.
Fires when a payment intent is cancelled.
Write-only. When set, Nuvion signs each delivery using an HMAC derived from this secret. The raw value is never returned after creation — store it securely before leaving the page. See Verifying signatures for how to validate incoming requests. Optional short description to identify the webhook in the dashboard.
Optional list of tags for organizing webhooks.
Webhook status. One of active or inactive. Defaults to active at creation.
Read-only delivery statistics for this webhook. Total number of delivery attempts made for this webhook.
total_webhooks_successful
Number of deliveries that received a 2xx response.
Number of deliveries that did not receive a 2xx response after all retries.
Unix timestamp in milliseconds of the most recent delivery attempt.
{ "id" : "wh_01HXYZ9900ABCD" , "entity_id" : "ent_01HXYZ1234ABCD" , "url" : "https://webhooks.example.com/nuvion" , "expires_in" : 31536000 , "enabled_events" : { "inflows" : { "created" : true , "completed" : true , "failed" : true , "cancelled" : false , "refunded" : false }, "outflows" : { "created" : true , "completed" : true , "failed" : true , "cancelled" : false , "refunded" : false } }, "description" : "Production payment notifications" , "tags" : [ "payments" , "production" ], "status" : "active" , "stats" : { "total_webhooks_sent" : 1482 , "total_webhooks_successful" : 1479 , "total_webhooks_failed" : 3 , "last_webhook_event" : 1744056000000 } }
Create a webhook Registers a new webhook endpoint for the authenticated entity.
POST /entity-webhookscurl -X POST https://api.nuvion.dev/entity-webhooks \ -H "Authorization: Bearer nv_test_abc123" \ -H "Content-Type: application/json" \ -d '{ "url": "https://webhooks.example.com/nuvion", "expires_in": 31536000, "enabled_events": { "inflows": { "created": true, "completed": true, "failed": true } } }'
Request parameters The HTTPS endpoint Nuvion will POST events to. Must begin with https://. Invalid URLs or non-HTTPS URLs are rejected.
Duration in seconds until the webhook expires. After expiry, deliveries stop and the webhook status becomes inactive.
The events to subscribe to. Set all: true to subscribe to every event type, or configure individual event groups. At least one event must be enabled. See the Webhook object for the full structure of this field. Signing secret used to generate an HMAC signature on each delivery. The value is stored as a SHA-512 hash and cannot be retrieved after creation . Store it before leaving the page.
Short description to identify the webhook.
List of tags for organizing webhooks.
Initial status of the webhook. One of active or inactive. Defaults to active.
Response Returns 201 Created with the new webhook object.
{ "status" : "success" , "message" : "Webhook created successfully" , "data" : { "id" : "wh_01HXYZ9900ABCD" , "entity_id" : "ent_01HXYZ1234ABCD" , "url" : "https://webhooks.example.com/nuvion" , "expires_in" : 31536000 , "enabled_events" : { "inflows" : { "created" : true , "completed" : true , "failed" : true , "cancelled" : false , "refunded" : false } }, "description" : "Production payment notifications" , "tags" : [ "payments" , "production" ], "status" : "active" , "stats" : { "total_webhooks_sent" : 0 , "total_webhooks_successful" : 0 , "total_webhooks_failed" : 0 , "last_webhook_event" : null } } }
The secret field is not returned in this response or any subsequent response. Copy and store it immediately after creating the webhook.
Update a webhook Updates an existing webhook. Only the fields you include are changed; omitted fields retain their current values.
PATCH /entity-webhooks/:webhookIdcurl -X PATCH https://api.nuvion.dev/entity-webhooks/wh_01HXYZ9900ABCD \ -H "Authorization: Bearer nv_test_abc123" \ -H "Content-Type: application/json" \ -d '{ "enabled_events": { "all": true }, "status": "active" }'
Request parameters The ID of the webhook to update.
New HTTPS delivery URL. Must begin with https://.
New expiry duration in seconds, measured from the time of this update.
Replaces the entire enabled_events configuration. Set all: true to subscribe to every event type.
Replaces the signing secret. The new value is stored as a SHA-512 hash and cannot be retrieved after this call.
Set to active or inactive. Setting to inactive pauses all deliveries without deleting the webhook.
Response Returns 200 OK with the updated webhook object.
{ "status" : "success" , "message" : "Webhook edited successfully" , "data" : { "id" : "wh_01HXYZ9900ABCD" , "entity_id" : "ent_01HXYZ1234ABCD" , "url" : "https://webhooks.example.com/nuvion" , "expires_in" : 31536000 , "enabled_events" : { "all" : true }, "description" : "Production payment notifications" , "tags" : [ "payments" , "production" ], "status" : "active" , "stats" : { "total_webhooks_sent" : 1482 , "total_webhooks_successful" : 1479 , "total_webhooks_failed" : 3 , "last_webhook_event" : 1744056000000 } } }
Get a webhook Retrieves a single webhook by ID.
GET /entity-webhooks/:webhookIdcurl https://api.nuvion.dev/entity-webhooks/wh_01HXYZ9900ABCD \ -H "Authorization: Bearer nv_test_abc123"
Request parameters The ID of the webhook to retrieve.
Response Returns 200 OK with the webhook object.
{ "status" : "success" , "message" : "Webhook fetched successfully" , "data" : { "id" : "wh_01HXYZ9900ABCD" , "entity_id" : "ent_01HXYZ1234ABCD" , "url" : "https://webhooks.example.com/nuvion" , "expires_in" : 31536000 , "enabled_events" : { "inflows" : { "created" : true , "completed" : true , "failed" : true , "cancelled" : false , "refunded" : false }, "outflows" : { "created" : true , "completed" : true , "failed" : true , "cancelled" : false , "refunded" : false } }, "description" : "Production payment notifications" , "tags" : [ "payments" , "production" ], "status" : "active" , "stats" : { "total_webhooks_sent" : 1482 , "total_webhooks_successful" : 1479 , "total_webhooks_failed" : 3 , "last_webhook_event" : 1744056000000 } } }
List webhooks Returns a paginated list of all webhooks for the authenticated entity.
GET /entity-webhookscurl "https://api.nuvion.dev/entity-webhooks?limit=20" \ -H "Authorization: Bearer nv_test_abc123"
Request parameters Number of results per page. Between 1 and 100. Defaults to 20.
ULID pagination cursor from a previous response. Omit for the first page.
Response Returns 200 OK with a paginated list of webhook objects.
{ "status" : "success" , "message" : "Webhooks fetched successfully" , "data" : [ { "id" : "wh_01HXYZ9900ABCD" , "entity_id" : "ent_01HXYZ1234ABCD" , "url" : "https://webhooks.example.com/nuvion" , "expires_in" : 31536000 , "enabled_events" : { "all" : true }, "description" : "Production payment notifications" , "tags" : [ "payments" , "production" ], "status" : "active" , "stats" : { "total_webhooks_sent" : 1482 , "total_webhooks_successful" : 1479 , "total_webhooks_failed" : 3 , "last_webhook_event" : 1744056000000 } } ], "meta" : { "pagination" : { "limit" : 20 , "total_count" : 3 , "has_next" : false , "has_previous" : false , "next_cursor" : null , "previous_cursor" : null }, "filters_applied" : { "sort" : { "field" : "created" , "order" : "desc" } } } }
Delete a webhook Permanently deletes a webhook. Nuvion stops delivering events to the endpoint immediately.
DELETE /entity-webhooks/:webhookIdcurl -X DELETE https://api.nuvion.dev/entity-webhooks/wh_01HXYZ9900ABCD \ -H "Authorization: Bearer nv_test_abc123"
Request parameters The ID of the webhook to delete.
Response Returns 200 OK confirming deletion.
{ "status" : "success" , "message" : "Webhook deleted successfully" , "data" : { "id" : "wh_01HXYZ9900ABCD" } }
Deletion is irreversible. All delivery history is retained in logs, but the webhook configuration and endpoint registration are permanently removed.
The Webhook Log object Each delivery attempt is recorded as a log entry. Logs are immutable and retained regardless of delivery outcome.
Unique log entry identifier.
The ID of the entity this log belongs to.
The ID of the webhook that triggered this delivery.
The URL this delivery was sent to at the time of the attempt.
The full HTTP request sent to the webhook endpoint, including headers and body. Any signing secrets or authentication tokens in headers are obfuscated.
URL query parameters included in the delivery request, if any.
The HTTP response received from the webhook endpoint, including status code, headers, and body.
Timestamps for the delivery lifecycle. Unix timestamp in milliseconds when Nuvion initiated the delivery.
Unix timestamp in milliseconds when the endpoint responded (or the attempt timed out).
List webhook logs Returns a paginated list of delivery log entries for the authenticated entity.
GET /webhook-logscurl "https://api.nuvion.dev/webhook-logs?limit=20" \ -H "Authorization: Bearer nv_test_abc123"
Request parameters Number of results per page. Between 1 and 100. Defaults to 20.
ULID pagination cursor from a previous response. Omit for the first page.
Response Returns 200 OK with a paginated list of log objects.
{ "status" : "success" , "message" : "Webhooks fetched successfully" , "data" : [ { "id" : "whl_01HXYZ0011EFGH" , "entity_id" : "ent_01HXYZ1234ABCD" , "entity_webhook_id" : "wh_01HXYZ9900ABCD" , "url" : "https://webhooks.example.com/nuvion" , "request" : { "method" : "POST" , "headers" : { "Content-Type" : "application/json" , "X-Nuvion-Signature" : "sha512=••••••••" }, "body" : { "event" : "inflows.completed" , "data" : { "id" : "inf_01HXYZ5566IJKL" } } }, "query" : {}, "response" : { "status" : 200 , "headers" : { "Content-Type" : "application/json" }, "body" : { "received" : true } }, "duration" : { "request_received" : 1744056000000 , "response_sent" : 1744056000312 } } ] }
Signing secrets and authentication tokens in request headers are obfuscated in log entries and cannot be recovered from logs.
Send a test event Sends a simulated event to an existing webhook endpoint. Use this to verify your endpoint is reachable and handling payloads correctly without waiting for a real event.
POST /webhook-testscurl -X POST https://api.nuvion.dev/webhook-tests \ -H "Authorization: Bearer nv_test_abc123" \ -H "Content-Type: application/json" \ -d '{ "entity_webhook_id": "wh_01HXYZ9900ABCD", "event_group": "inflows", "event_name": "completed" }'
Request parameters The ID of the webhook to send the test event to.
The event group to simulate. One of accounts, account_details, inflows, outflows, entities, funding_sessions, or payment_intent.
The specific event to simulate within the group. One of created, updated, deleted, completed, failed, cancelled, or refunded. Not all combinations of event_group and event_name are valid — for example, funding_sessions.created does not exist. Refer to the enabled_events structure for supported combinations. Response Returns 201 Created confirming the test was dispatched.
{ "status" : "success" , "message" : "Test Webhook sent successfully" , "data" : {} }
Test events appear in webhook logs the same as live events. Check the logs to inspect the full request and response if your endpoint didn’t receive the payload as expected. 