Skip to Content
better-auth-nuvion

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:

  1. the headers x-nuvion-event-id, x-nuvion-event-timestamp and x-nuvion-event-signature are present,
  2. the signature is the lowercase hex HMAC-SHA256 of {x-nuvion-event-timestamp}.{raw body}, keyed by your webhook secret (the whole nv_wsk_... string), compared in constant time,
  3. optionally, the timestamp is within webhookToleranceMs of 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

EventWhat the plugin does
inflows.completedMatches the payment by unique_reference (then narration), checks the amount, creates and executes the legs
outflows.completedMarks the leg completed; the payment becomes settled when all legs are
outflows.failed, outflows.cancelledMarks the leg failed so it can be retried
outflows.refundedAcknowledged; not yet mapped back to a payment (see Status)
anything elseAcknowledged 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 unique nuvionEvent row.
  • 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_in is 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.

On this page