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) |
entities.updated | Confirms the status with Nuvion, then runs your onEntityUpdated hook |
| 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.
What the plugin checks before it acts
A valid signature proves the event came from Nuvion's webhook, not that its body is true. With confirmEvents on (the default), the plugin asks Nuvion first:
inflows.completed: it retrieves the funding session it created at checkout (saved on the payment) and requires statussettledwith the same reference, amount and currency. If Nuvion says otherwise the event is answeredunconfirmed-mismatchand nothing moves. A session that is not settled yet givesnot-confirmed; a scheduled reconcile settles it once it is.outflows.completedandoutflows.failed: it looks up the transfer by its reference. A finished transfer is settled from Nuvion's record, which wins if the event body disagrees. A transfer that is still pending, or not found, givesnot-confirmedand the leg stayssentuntil a redelivery or reconcile.- A payment made before 0.4 has no saved session, so the session id in the event is used to look it up, and Nuvion's answer is still checked against the payment's reference and amount.
Set confirmEvents: false to trust a verified signature alone.
Response codes
| Code | When |
|---|---|
200 | Processed, ignored, duplicate, not confirmed, or a setup problem (logged, and the affected leg is marked failed so you can retry it). |
401 | Bad or missing signature, or an unknown tenant. |
400 | No x-nuvion-event-id header. |
503 | A temporary failure: Nuvion was unreachable or answered 5xx or 429 while the plugin was confirming the event. Nuvion retries the delivery. |
Only 503 asks for a retry. Anything else would fail the same way every time and, after three failures in 24 hours, get your webhook blacklisted, so those are acknowledged, logged and left for retry or reconcile.
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.