Webhooks
How the plugin receives Nuvion events, verifies them, de-duplicates them, and how to register and debug your webhook.
Nuvion tells your app that a customer paid, and that each transfer finished, with signed webhooks. The plugin receives them at:
POST /api/auth/nuvion/webhook (under your Better Auth base path)The route is public by design: its only authentication is the signature.
Verification
Nuvion signs every delivery. The plugin checks:
- the headers
x-nuvion-event-id,x-nuvion-event-timestampandx-nuvion-event-signatureare present, - the signature is the lowercase hex HMAC-SHA256 of
{x-nuvion-event-timestamp}.{raw body}, keyed by your webhook secret (the wholenv_wsk_...string), compared in constant time, - optionally, the timestamp is within
webhookToleranceMsof now (a replay guard).
A bad or missing signature returns 401. The timestamp is an ISO 8601 string such as 2026-11-18T11:59:47.522Z, and the signature covers the raw bytes of the body, which is why the plugin handles this route before Better Auth parses the request.
Set a replay window
webhookToleranceMs is off by default, so the timestamp is signed but not checked. Set it (for example 5 * 60_000) so a captured delivery cannot be replayed later.
Events
| Event | What the plugin does |
|---|---|
inflows.completed | Matches the payment by unique_reference (then narration), checks the amount, creates and executes the legs |
outflows.completed | Marks the leg completed; the payment becomes settled when all legs are |
outflows.failed, outflows.cancelled | Marks the leg failed so it can be retried |
outflows.refunded | Acknowledged; not yet mapped back to a payment (see Status) |
| anything else | Acknowledged and ignored |
Responses are 200 with a small status body (processed, duplicate-event, unknown-payment, ignored, ...). Returning 200 for events the plugin ignores stops Nuvion from retrying them.
Safe to receive twice
- Duplicate event ids are ignored (
duplicate-event): the id is claimed in a uniquenuvionEventrow. - Same payment, new event id does not pay out twice: the payment's status is a guarded transition, so only the first inflow creates legs.
- Late events for an old attempt of a leg are ignored.
Register the webhook
Create it with POST /entity-webhooks (see Installation). Things to know:
- The URL must be https. Nuvion does not deliver to plain http.
expires_inis required by the API, but Nuvion never expires the webhook.- The signing secret is returned once, in the create response.
- The key needs a role that can manage webhooks (Owner or Developer).
Debug with Hookbox
Hookbox is a webhook inbox for testing. Create an inbox (no account), register its capture URL as a second Nuvion webhook, and every delivery shows up with its headers, body and timing. You can also paste the signing secret there to check a signature, and replay a captured delivery to your own endpoint.
Hookbox only shows what Nuvion sends to the inbox URL, so register it as an additional webhook alongside your real one. Do not send real customer data or production secrets to it.
Running more than one tenant
The plugin takes one webhookSecret. If each of your customers brings their own Nuvion webhook, see Multi-tenant keys for the pattern the example uses.