Webhooks

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. See Webhooks overview for the delivery model, retries, and signature verification.

The Webhook object

string

Unique webhook identifier.

string

The ID of the entity this webhook belongs to. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

string

The HTTPS endpoint Nuvion delivers events to. Must use the https protocol.

number

Duration in seconds until the webhook expires. After expiry, no further events are delivered and the webhook status becomes inactive.

object

The set of events this webhook is subscribed to.

Show enabled_events fields

boolean

When true, subscribes to every event type. Overrides all other selections in this object.

object

Entity lifecycle events.

Show entities fields

boolean

Fires when a new entity is created.

boolean

Fires when an entity is updated, for example when its status changes.

object

Account lifecycle events.

Show accounts fields

boolean

Fires when a new account is created.

boolean

Fires when an account is updated.

boolean

Fires when an account is deleted.

object

Account details lifecycle events (bank account numbers, wallet addresses).

Show account_details fields

boolean

Fires when account details are created.

boolean

Fires when account details are updated.

boolean

Fires when account details are deleted.

object

Incoming payment events.

Show inflows fields

boolean

Fires when an inflow settles successfully.

boolean

Fires when an inflow fails.

object

Outgoing payment events.

Show outflows fields

boolean

Fires when an outflow is initiated.

boolean

Fires when an outflow settles successfully.

boolean

Fires when an outflow fails.

boolean

Fires when an outflow is cancelled.

boolean

Fires when an outflow is refunded.

object

Funding session events.

Show funding_sessions fields

boolean

Fires when a funding session is updated.

object

Payment intent events.

Show payment_intent fields

boolean

Fires when a payment intent is completed.

boolean

Fires when a payment intent fails.

boolean

Fires when a payment intent is cancelled.

object

Payment dispute events.

Show payment_dispute fields

boolean

Fires when a payment dispute is opened.

boolean

Fires when a payment dispute is resolved.

object

Payment refund events.

Show payment_refund fields

boolean

Fires when a payment refund settles successfully.

boolean

Fires when a payment refund fails.

object

Card lifecycle events.

Show cards fields

boolean

Fires when a new card is issued.

boolean

Fires when a card is frozen.

boolean

Fires when a card is unfrozen.

boolean

Fires when a card is deleted.

string[]

Read-only. A flattened summary of the enabled events, using group.all where every event in a group is enabled. e.g. ["accounts.all", "outflows.all"].

string

System-generated signing secret. Nuvion derives an HMAC from this value to sign each delivery. Returned once, at creation or when rotated via rotate_secret: store it securely before leaving the page. It is never returned on subsequent requests. See Verifying signatures for how to validate incoming requests.

string

Optional short description to identify the webhook in the dashboard.

string[]

Optional list of tags for organizing webhooks.

string

Webhook status. One of active or inactive. Defaults to active at creation.

number

Unix timestamp in milliseconds when the webhook was created.

number

Unix timestamp in milliseconds when the webhook was last updated.

number

0 if the webhook is active. Non-zero if the webhook has been deleted.

object

Read-only delivery statistics for this webhook.

Show stats fields

number

Total number of delivery attempts made for this webhook.

number

Number of deliveries that received a 2xx response.

number

Number of deliveries that did not receive a 2xx response after all retries.

number

Unix timestamp in milliseconds of the most recent delivery attempt.

Example

{
  "status": "success",
  "message": "Webhook fetched successfully",
  "data": {
    "id": "01HXYZ9001ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "url": "https://webhooks.example.com/nuvion",
    "expires_in": 31536000,
    "enabled_events": {
      "all": false,
      "entities": {
        "created": false,
        "updated": false
      },
      "accounts": {
        "created": true,
        "updated": true,
        "deleted": true
      },
      "account_details": {
        "created": true,
        "updated": true,
        "deleted": true
      },
      "inflows": {
        "completed": true,
        "failed": true
      },
      "outflows": {
        "created": true,
        "completed": true,
        "failed": true,
        "cancelled": false,
        "refunded": false
      },
      "funding_sessions": {
        "updated": true
      },
      "payment_intent": {
        "completed": true,
        "failed": true,
        "cancelled": false
      },
      "payment_dispute": {
        "created": true,
        "completed": true
      },
      "payment_refund": {
        "completed": true,
        "failed": true
      },
      "cards": {
        "created": true,
        "frozen": true,
        "unfrozen": true,
        "deleted": true
      }
    },
    "preferred_events": [
      "accounts.all",
      "account_details.all",
      "inflows.all",
      "funding_sessions.all",
      "payment_dispute.all",
      "payment_refund.all",
      "cards.all"
    ],
    "description": "Production payment notifications",
    "tags": ["payments", "production"],
    "status": "active",
    "created": 1744056000000,
    "updated": 1744056000000,
    "deleted": 0,
    "stats": {
      "total_webhooks_sent": 1482,
      "total_webhooks_successful": 1479,
      "total_webhooks_failed": 3,
      "last_webhook_event": 1744056000000
    }
  }
}

Create a webhook

POST /entity-webhooks Registers a new webhook endpoint for the authenticated entity.

curl -X POST https://api.nuvion.dev/entity-webhooks \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://nuvion-web.vercel.app/put",
    "description": "Payout tracking webhook",
    "expires_in": 2592000,
    "enabled_events": {
        "account_details": {
            "created": true,
            "deleted": true,
            "updated": true
        },
        "outflows": {
            "failed": true,
            "cancelled": true,
            "refunded": true,
            "created": true,
            "completed": true
        }
    },
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS"
  }'

curl -X POST https://api.nuvion.dev/entity-webhooks \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhooks.example.com/nuvion",
    "expires_in": 31536000,
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "enabled_events": {
      "all": true
    },
    "description": "Production payment notifications",
    "tags": ["payments", "production"]
  }'

Request parameters

string

required

The HTTPS endpoint Nuvion posts events to. Must begin with https://. Invalid URLs or non-HTTPS URLs are rejected.

number

required

Duration in seconds until the webhook expires. After expiry, deliveries stop and the webhook status becomes inactive.

string

The ID of the entity this webhook belongs to. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

object

required

The events to subscribe to. Set all to subscribe to every event, or enable specific events within one or more groups. See enabled_events fields for the full group structure.

boolean

When true, subscribes to every event type. Overrides all other selections in this object.

Show entities

The entity events to subscribe to.

boolean

Fires when a new entity is created.

boolean

Fires when an entity is updated, for example when its status changes.

Show accounts

The account events to subscribe to.

boolean

Fires when a new account is created.

boolean

Fires when an account is updated.

boolean

Fires when an account is deleted.

Show account_details

The account details events to subscribe to.

boolean

Fires when account details are created.

boolean

Fires when account details are updated.

boolean

Fires when account details are deleted.

Show inflows

The inflow events to subscribe to.

boolean

Fires when an inflow settles successfully.

boolean

Fires when an inflow fails.

Show outflows

The outflow events to subscribe to.

boolean

Fires when an outflow is initiated.

boolean

Fires when an outflow settles successfully.

boolean

Fires when an outflow fails.

boolean

Fires when an outflow is cancelled.

boolean

Fires when an outflow is refunded.

Show funding_sessions

The funding session events to subscribe to.

boolean

Fires when a funding session is updated.

Show payment_intent

The payment intent events to subscribe to.

boolean

Fires when a payment intent is completed.

boolean

Fires when a payment intent fails.

boolean

Fires when a payment intent is cancelled.

Show payment_dispute

The payment dispute events to subscribe to.

boolean

Fires when a payment dispute is opened.

boolean

Fires when a payment dispute is resolved.

Show payment_refund

The payment refund events to subscribe to.

boolean

Fires when a payment refund settles successfully.

boolean

Fires when a payment refund fails.

Show cards

The card events to subscribe to.

boolean

Fires when a new card is issued.

boolean

Fires when a card is frozen.

boolean

Fires when a card is unfrozen.

boolean

Fires when a card is deleted.

Response

Returns 201 Created with the new webhook object.

{
  "status": "success",
  "message": "Webhook created successfully",
  "data": {
    "id": "01HXYZ9006ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "url": "https://nuvion-web.vercel.app/put",
    "expires_in": 2592000,
    "enabled_events": {
      "all": false,
      "entities": {
        "created": false,
        "updated": false
      },
      "accounts": {
        "created": false,
        "updated": false,
        "deleted": false
      },
      "account_details": {
        "created": true,
        "updated": true,
        "deleted": true
      },
      "inflows": {
        "completed": false,
        "failed": false
      },
      "outflows": {
        "created": true,
        "completed": true,
        "failed": true,
        "cancelled": true,
        "refunded": true
      },
      "funding_sessions": {
        "updated": false
      },
      "payment_intent": {
        "completed": false,
        "failed": false,
        "cancelled": false
      },
      "payment_dispute": {
        "created": false,
        "completed": false
      },
      "payment_refund": {
        "completed": false,
        "failed": false
      },
      "cards": {
        "created": false,
        "frozen": false,
        "unfrozen": false,
        "deleted": false
      }
    },
    "preferred_events": [
      "account_details.all",
      "outflows.all"
    ],
    "secret": "7f3a91c4e8b2d5f60a1c7e9b3d8f2a4c6e0b5d9f1a3c7e2b4d6f8a0c2e4b6d81",
    "description": "Payout tracking webhook",
    "tags": [],
    "status": "active",
    "created": 1787286828480,
    "updated": 1787286828480,
    "deleted": 0,
    "stats": {
      "total_webhooks_sent": 0,
      "total_webhooks_successful": 0,
      "total_webhooks_failed": 0,
      "last_webhook_event": 0
    }
  }
}

{
  "status": "success",
  "message": "Webhook created successfully",
  "data": {
    "id": "01HXYZ9007ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "url": "https://webhooks.example.com/nuvion",
    "expires_in": 31536000,
    "enabled_events": {
      "all": true,
      "entities": {
        "created": false,
        "updated": false
      },
      "accounts": {
        "created": false,
        "updated": false,
        "deleted": false
      },
      "account_details": {
        "created": false,
        "updated": false,
        "deleted": false
      },
      "inflows": {
        "completed": false,
        "failed": false
      },
      "outflows": {
        "created": false,
        "completed": false,
        "failed": false,
        "cancelled": false,
        "refunded": false
      },
      "funding_sessions": {
        "updated": false
      },
      "payment_intent": {
        "completed": false,
        "failed": false,
        "cancelled": false
      },
      "payment_dispute": {
        "created": false,
        "completed": false
      },
      "payment_refund": {
        "completed": false,
        "failed": false
      },
      "cards": {
        "created": false,
        "frozen": false,
        "unfrozen": false,
        "deleted": false
      }
    },
    "preferred_events": [
      "all"
    ],
    "secret": "7f3a91c4e8b2d5f60a1c7e9b3d8f2a4c6e0b5d9f1a3c7e2b4d6f8a0c2e4b6d81",
    "description": "Production payment notifications",
    "tags": ["payments", "production"],
    "status": "active",
    "created": 1787286900000,
    "updated": 1787286900000,
    "deleted": 0,
    "stats": {
      "total_webhooks_sent": 0,
      "total_webhooks_successful": 0,
      "total_webhooks_failed": 0,
      "last_webhook_event": 0
    }
  }
}

Copy and store the secret immediately after creating the webhook.

Update a webhook

PATCH /entity-webhooks/:id Updates an existing webhook. Only the fields you include are changed; omitted fields retain their current values.

curl -X PATCH https://api.nuvion.dev/entity-webhooks/:id \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://nuvion-web.vercel.app/put-request",
    "rotate_secret": true
  }'

curl -X PATCH https://api.nuvion.dev/entity-webhooks/:id \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://nuvion-web.vercel.app/patchh"
  }'

Path parameters

string

required

The ID of the webhook to update.

Request parameters

string

New HTTPS delivery URL. Must begin with https://.

boolean

Whether to rotate the webhook’s signing secret. Defaults to false.

string

The ID of the entity this webhook belongs to. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Set rotate_secret to true if you’re rotating your secret key. The new value is returned once in the response, the same as at creation; it isn’t returned on later requests.

Response

Returns 200 OK with the updated webhook object.

{
  "status": "success",
  "message": "Webhook updated successfully",
  "data": {
    "id": "01HXYZ9005ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "url": "https://nuvion-web.vercel.app/put-request",
    "expires_in": 2592000,
    "enabled_events": {
      "all": false,
      "entities": {
        "created": false,
        "updated": false
      },
      "accounts": {
        "created": false,
        "updated": false,
        "deleted": false
      },
      "account_details": {
        "created": true,
        "updated": true,
        "deleted": true
      },
      "inflows": {
        "completed": false,
        "failed": false
      },
      "outflows": {
        "created": true,
        "completed": true,
        "failed": true,
        "cancelled": true,
        "refunded": true
      },
      "funding_sessions": {
        "updated": false
      },
      "payment_intent": {
        "completed": false,
        "failed": false,
        "cancelled": false
      },
      "payment_dispute": {
        "created": false,
        "completed": false
      },
      "payment_refund": {
        "completed": false,
        "failed": false
      },
      "cards": {
        "created": false,
        "frozen": false,
        "unfrozen": false,
        "deleted": false
      }
    },
    "preferred_events": [
      "account_details.all",
      "outflows.all"
    ],
    "secret": "7f3a91c4e8b2d5f60a1c7e9b3d8f2a4c6e0b5d9f1a3c7e2b4d6f8a0c2e4b6d81",
    "description": "Payout tracking webhook",
    "tags": [],
    "status": "active",
    "created": 1781872625218,
    "updated": 1781872792881,
    "deleted": 0,
    "stats": {
      "total_webhooks_sent": 0,
      "total_webhooks_successful": 0,
      "total_webhooks_failed": 0,
      "last_webhook_event": 0
    }
  }
}

{
  "status": "success",
  "message": "Webhook updated successfully",
  "data": {
    "id": "01HXYZ9004ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "url": "https://nuvion-web.vercel.app/patchh",
    "expires_in": 2592000,
    "enabled_events": {
      "all": true,
      "entities": {
        "created": false,
        "updated": false
      },
      "accounts": {
        "created": false,
        "updated": false,
        "deleted": false
      },
      "account_details": {
        "created": false,
        "updated": false,
        "deleted": false
      },
      "inflows": {
        "completed": false,
        "failed": false
      },
      "outflows": {
        "created": false,
        "completed": false,
        "failed": false,
        "cancelled": false,
        "refunded": false
      },
      "funding_sessions": {
        "updated": false
      },
      "payment_intent": {
        "completed": false,
        "failed": false,
        "cancelled": false
      },
      "payment_dispute": {
        "created": false,
        "completed": false
      },
      "payment_refund": {
        "completed": false,
        "failed": false
      },
      "cards": {
        "created": false,
        "frozen": false,
        "unfrozen": false,
        "deleted": false
      }
    },
    "preferred_events": [
      "all"
    ],
    "description": "General event notifications",
    "tags": [],
    "status": "active",
    "created": 1781871959611,
    "updated": 1781872978628,
    "deleted": 0,
    "stats": {
      "total_webhooks_sent": 0,
      "total_webhooks_successful": 0,
      "total_webhooks_failed": 0,
      "last_webhook_event": 0
    }
  }
}

Get a webhook

GET /entity-webhooks/:webhookId Retrieves a single webhook by ID.

curl "https://api.nuvion.dev/entity-webhooks/01HXYZ9001ABCDEFGHJKMNPQRS?entity_id=01HXYZ1234ABCDEFGHJKMNPQRS" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Path parameters

string

required

The ID of the webhook to retrieve.

Query parameters

string

The ID of the entity this webhook belongs to. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Response

Returns 200 OK with the webhook object.

Response

{
  "status": "success",
  "message": "Webhook fetched successfully",
  "data": {
    "id": "01HXYZ9001ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "url": "https://webhooks.example.com/nuvion",
    "expires_in": 31536000,
    "enabled_events": {
      "all": false,
      "entities": {
        "created": false,
        "updated": false
      },
      "accounts": {
        "created": true,
        "updated": true,
        "deleted": true
      },
      "account_details": {
        "created": true,
        "updated": true,
        "deleted": true
      },
      "inflows": {
        "completed": true,
        "failed": true
      },
      "outflows": {
        "created": true,
        "completed": true,
        "failed": true,
        "cancelled": false,
        "refunded": false
      },
      "funding_sessions": {
        "updated": true
      },
      "payment_intent": {
        "completed": true,
        "failed": true,
        "cancelled": false
      },
      "payment_dispute": {
        "created": true,
        "completed": true
      },
      "payment_refund": {
        "completed": true,
        "failed": true
      },
      "cards": {
        "created": true,
        "frozen": true,
        "unfrozen": true,
        "deleted": true
      }
    },
    "preferred_events": [
      "accounts.all",
      "account_details.all",
      "inflows.all",
      "funding_sessions.all",
      "payment_dispute.all",
      "payment_refund.all",
      "cards.all"
    ],
    "description": "Production payment notifications",
    "tags": ["payments", "production"],
    "status": "active",
    "created": 1744056000000,
    "updated": 1744056000000,
    "deleted": 0,
    "stats": {
      "total_webhooks_sent": 1482,
      "total_webhooks_successful": 1479,
      "total_webhooks_failed": 3,
      "last_webhook_event": 1744056000000
    }
  }
}

List webhooks

GET /entity-webhooks Returns a paginated list of all webhooks for the authenticated entity.

curl "https://api.nuvion.dev/entity-webhooks?limit=20&entity_id=01HXYZ1234ABCDEFGHJKMNPQRS" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Query parameters

integer

Number of results per page. Between 1 and 100. Defaults to 20.

string

ULID pagination cursor from a previous response. Omit for the first page.

string

The ID of the entity this webhook belongs to. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Response

Returns 200 OK with a paginated list of webhook objects.

Response

{
  "status": "success",
  "message": "Webhooks fetched successfully",
  "data": {
    "data": [
      {
        "id": "01HXYZ9009ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "url": "https://webhooks.example.com/nuvion",
        "expires_in": 3155695200000,
        "enabled_events": {
          "all": true,
          "entities": {
            "created": false,
            "updated": false
          },
          "accounts": {
            "created": false,
            "updated": false,
            "deleted": false
          },
          "account_details": {
            "created": false,
            "updated": false,
            "deleted": false
          },
          "inflows": {
            "completed": false,
            "failed": false
          },
          "outflows": {
            "created": false,
            "completed": false,
            "failed": false,
            "cancelled": false,
            "refunded": false
          },
          "funding_sessions": {
            "updated": false
          },
          "payment_intent": {
            "completed": false,
            "failed": false,
            "cancelled": false
          },
          "payment_dispute": {
            "created": false,
            "completed": false
          },
          "payment_refund": {
            "completed": false,
            "failed": false
          },
          "cards": {
            "created": false,
            "frozen": false,
            "unfrozen": false,
            "deleted": false
          }
        },
        "preferred_events": [
          "all"
        ],
        "tags": [],
        "status": "active",
        "created": 1787673119614,
        "updated": 1787673119614,
        "deleted": 0,
        "stats": {
          "total_webhooks_sent": 29,
          "total_webhooks_successful": 29,
          "total_webhooks_failed": 0,
          "last_webhook_event": 1787855480062
        }
      }
    ],
    "meta": {
      "pagination": {
        "order": "desc",
        "has_next": false,
        "limit": 20,
        "has_previous": false,
        "next_cursor": null,
        "previous_cursor": null
      },
      "filters_applied": {
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "sort": {
          "field": "_id",
          "order": "desc"
        }
      }
    }
  }
}

Delete a webhook

DELETE /entity-webhooks/:webhookId Permanently deletes a webhook. Nuvion stops delivering events to the endpoint immediately.

curl -X DELETE https://api.nuvion.dev/entity-webhooks/01HXYZ9001ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS"
  }'

Path parameters

string

required

The ID of the webhook to delete.

Request parameters

string

The ID of the entity this webhook belongs to. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Response

Returns 200 OK confirming deletion.

Response

{
  "status": "success",
  "message": "Webhook deleted successfully",
  "data": {
    "id": "01HXYZ9001ABCDEFGHJKMNPQRS"
  }
}

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.

string

Unique log entry identifier.

string

The ID of the entity this log belongs to.

string

The ID of the event that triggered this delivery.

string

The ID of the webhook that triggered this delivery.

string

The URL this delivery was sent to at the time of the attempt.

object

The request Nuvion sent to the webhook endpoint.

Show request fields

object

Headers sent with the delivery, including Content-Type, X-Nuvion-Event-Id, X-Nuvion-Event-Signature, and X-Nuvion-Event-Timestamp. See Verifying signatures for how to validate X-Nuvion-Event-Signature.

object

The payload delivered to the endpoint. For live events, matches the event and data shape of the triggering event; see Event types for the full payload schema per event. For deliveries triggered by Send a test event, this is {event_group, event_name} instead.

object

The response received from the webhook endpoint.

Show response fields

string

Raw response body returned by the endpoint.

number

HTTP status code returned by the endpoint.

object

Timestamps for the delivery lifecycle.

Show duration fields

number

Unix timestamp in milliseconds when Nuvion sent the delivery.

number

Unix timestamp in milliseconds when the endpoint responded.

number

Unix timestamp in milliseconds when the log entry was created.

number

Unix timestamp in milliseconds when the log entry was last updated.

number

0 for all log entries. Logs are immutable and never deleted.

List webhook logs

GET /webhook-logs Returns a paginated list of delivery log entries for the authenticated entity.

curl "https://api.nuvion.dev/webhook-logs?limit=20&entity_id=01HXYZ1234ABCDEFGHJKMNPQRS" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Query parameters

integer

Number of results per page. Between 1 and 100. Defaults to 20.

string

ULID pagination cursor from a previous response. Omit for the first page.

string

The ID of the entity this webhook belongs to. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Response

Returns 200 OK with a paginated list of log objects.

Response

{
  "status": "success",
  "message": "Webhook logs fetched successfully",
  "data": {
    "data": [
      {
        "id": "01HXYZ9002ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "event_id": "01HXYZ9008ABCDEFGHJKMNPQRS",
        "entity_webhook_id": "01HXYZ9001ABCDEFGHJKMNPQRS",
        "url": "https://webhooks.example.com/nuvion",
        "request": {
          "headers": {
            "Content-Type": "application/json",
            "X-Nuvion-Event-Id": "01HXYZ9008ABCDEFGHJKMNPQRS",
            "X-Nuvion-Event-Signature": "a8492a0d21bd5fd16bef2454bf305029ea205e5e331341b25a8231fff75edc43",
            "X-Nuvion-Event-Timestamp": "2026-08-27T18:31:19.719Z"
          },
          "body": {
            "event": "inflows.completed",
            "data": {
              "id": "01HXYZ9003ABCDEFGHJKMNPQRS"
            }
          }
        },
        "response": {
          "data": "OK",
          "status": 200
        },
        "duration": {
          "request_sent": 1744056000000,
          "response_received": 1744056000312
        },
        "created": 1744056000312,
        "updated": 1744056000312,
        "deleted": 0
      }
    ],
    "meta": {
      "pagination": {
        "order": "desc",
        "has_next": false,
        "limit": 20,
        "has_previous": false,
        "next_cursor": null,
        "previous_cursor": null
      },
      "filters_applied": {
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "sort": {
          "field": "_id",
          "order": "desc"
        }
      }
    }
  }
}

X-Nuvion-Event-Signature and the other delivery headers are recorded as sent. See Verifying signatures for how to validate them.

Send a test event

POST /webhook-tests Sends a test delivery to an existing webhook endpoint, so you can verify it’s reachable and correctly signs and receives deliveries without waiting for a real event.

curl -X POST https://api.nuvion.dev/webhook-tests \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_webhook_id": "01HXYZ9001ABCDEFGHJKMNPQRS",
    "event_group": "inflows",
    "event_name": "completed",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS"
  }'

Request parameters

string

required

The ID of the webhook to send the test event to.

string

required

The event group to simulate. One of entities, accounts, account_details, inflows, outflows, funding_sessions, payment_intent, payment_dispute, payment_refund, or cards.

string

required

The specific event to simulate within the group. One of created, updated, deleted, completed, failed, cancelled, refunded, frozen, or unfrozen.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.

string

The ID of the entity this webhook belongs to. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Response

Returns 201 Created confirming the test was dispatched.

Response

{
  "status": "success",
  "message": "Test Webhook sent successfully",
  "data": {}
}

The test delivery’s body only contains event_group and event_name, not the full event/data shape a real event payload has:

{
  "event_group": "inflows",
  "event_name": "completed"
}

Use this endpoint to confirm your webhook is reachable and that your signature verification works, not to test your handler’s parsing logic against realistic event data. See Event types for real payload shapes.

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.

API Reference

The Webhook object

Create a webhook

Request parameters

Response

Update a webhook

Path parameters

Request parameters

Response

Get a webhook

Path parameters

Query parameters

Response

List webhooks

Query parameters

Response

Delete a webhook

Path parameters

Request parameters

Response

The Webhook Log object

List webhook logs

Query parameters

Response

Send a test event

Request parameters

Response

What’s next

Webhooks overview

Event types

​The Webhook object

​Create a webhook

​Request parameters

​Response

​Update a webhook

​Path parameters

​Request parameters

​Response

​Get a webhook

​Path parameters

​Query parameters

​Response

​List webhooks

​Query parameters

​Response

​Delete a webhook

​Path parameters

​Request parameters

​Response

​The Webhook Log object

​List webhook logs

​Query parameters

​Response

​Send a test event

​Request parameters

​Response

​What’s next

Webhooks overview

Event types

The Webhook object

Create a webhook

Request parameters

Response

Update a webhook

Path parameters

Request parameters

Response

Get a webhook

Path parameters

Query parameters

Response

List webhooks

Query parameters

Response

Delete a webhook

Path parameters

Request parameters

Response

The Webhook Log object

List webhook logs

Query parameters

Response

Send a test event

Request parameters

Response

What’s next