Webhooks

Webhooks tell your server when your funding intents, payments and refunds change. Fulfil orders on funding.credited: it arrives only after the payment is verified, settled and credited, and it reaches you even when your user has closed the page.

1. Add an endpoint

In the dashboard, open Developers → Webhooks → Add endpoint, or create one with the SDK. The signing secret is returned once, when the endpoint is created. Store it with your other secrets.

const endpoint = await useroutr.webhooks.endpoints.create({
  url: "https://example.com/webhooks/useroutr",
  event_types: ["funding.credited", "funding.failed", "payment.rejected"],
});

endpoint.secret; // store as USEROUTR_WEBHOOK_SECRET

Pass ["*"] to receive every event, including types added later. Endpoint URLs must be public https:// addresses.

2. Verify and handle events

constructEvent checks the signature over the raw request body and returns the typed event. Never verify re-serialized JSON: the bytes must be exactly what was sent.

import { Useroutr, WebhookSignatureError } from "@useroutr/sdk";

const useroutr = new Useroutr({ apiKey: process.env.USEROUTR_API_KEY });

export async function POST(request: Request) {
  const payload = await request.text();

  let event;
  try {
    event = useroutr.webhooks.constructEvent({
      payload,
      signatureHeader: request.headers.get("useroutr-signature") ?? undefined,
      eventId: request.headers.get("useroutr-event-id") ?? undefined,
      secret: process.env.USEROUTR_WEBHOOK_SECRET!,
    });
  } catch (error) {
    if (error instanceof WebhookSignatureError) {
      return new Response("invalid signature", { status: 400 });
    }
    throw error;
  }

  if (event.type === "funding.credited") {
    await fulfilOrder(event.data.object.reference);
  }

  return new Response(null, { status: 200 });
}

import express from "express";
import { Useroutr, WebhookSignatureError } from "@useroutr/sdk";

const app = express();
const useroutr = new Useroutr({ apiKey: process.env.USEROUTR_API_KEY });

app.post("/webhooks/useroutr", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = useroutr.webhooks.constructEvent({
      payload: req.body,
      signatureHeader: req.headers["useroutr-signature"],
      eventId: req.headers["useroutr-event-id"],
      secret: process.env.USEROUTR_WEBHOOK_SECRET!,
    });
  } catch (error) {
    if (error instanceof WebhookSignatureError) {
      res.status(400).end();
      return;
    }
    throw error;
  }

  if (event.type === "funding.credited") {
    void fulfilOrder(event.data.object.reference);
  }

  res.status(200).end();
});

Answer 2xx quickly and do slow work afterwards. A request that takes longer than 10 seconds counts as failed.

3. Make your handler safe to repeat

The same event can arrive more than once. Every delivery of an event carries the same id and Useroutr-Event-Id, so record the ids you have handled and skip repeats. Treat a webhook as a signal: when it matters, read the current state with the SDK.

Events

Event	When	`data.object`
`funding.created`	A funding intent is created	Funding intent
`funding.partially_funded`	A payment covered part of the amount	Funding intent
`funding.payment_confirmed`	Payments cover the full amount	Funding intent
`funding.settling`	A settlement was created	Funding intent
`funding.settled`	The settlement was confirmed on chain	Funding intent
`funding.credited`	Your ledger was credited	Funding intent
`funding.failed`	Registration or settlement failed	Funding intent
`funding.expired`	The intent expired unpaid	Funding intent
`payment.rejected`	A payment did not satisfy its intent	Payment
`refund.created`	A refund was recorded	Refund
`refund.completed`	A refund was paid out	Refund
`refund.failed`	A refund could not be paid	Refund
`refund.destination_required`	A refund is waiting for you to name the account to pay; see Refunds	Refund

data.object is the resource as it is when the event is sent, which can already be further along than the event’s type. Use type for what happened and the object for the current state.

{
  "id": "evt_0d5e8c26",
  "object": "event",
  "type": "funding.credited",
  "api_version": "1",
  "application_id": "app_5c1e0a9f",
  "funding_intent_id": "fi_2d6a91c4",
  "created_at": "2026-09-26T09:41:12.000Z",
  "data": { "object": { "id": "fi_2d6a91c4", "object": "funding_intent", "status": "CREDITED" } }
}

Retries

Your response	Result
`2xx`	Delivered
`408`, `425`, `429`, `5xx`, a redirect, a timeout or a connection error	Retried
Any other `4xx`	Failed, not retried

Retries back off exponentially, from 30 seconds up to an hour between attempts, for up to 8 attempts. Every attempt is recorded. Retry a failed delivery from the dashboard, or with the SDK:

for await (const delivery of useroutr.webhooks.deliveries.iterate({ status: "EXHAUSTED" })) {
  await useroutr.webhooks.deliveries.retry(delivery.id);
}

Every event is kept whether or not an endpoint received it, so you can replay what you missed with useroutr.webhooks.events.iterate().

Signatures in detail

The SDK does this for you. To verify by hand, read t and every v1 from the Useroutr-Signature header (t=<unix seconds>,v1=<hex>), then compute:

HMAC_SHA256(secret, `${t}.${eventId}.${rawBody}`)  →  hex

Accept if any v1 matches under a constant-time comparison and t is within five minutes.

Header	Value
`Useroutr-Signature`	`t=<unix seconds>,v1=<hex>`, with two `v1` values during a secret rotation
`Useroutr-Event-Id`	The event id
`Useroutr-Event-Type`	The event type
`Useroutr-Delivery-Id`	The delivery id, stable across retries

Rotating the secret

const { secret } = await useroutr.webhooks.endpoints.rotateSecret("whep_3b7a1f08");

For 24 hours both the old and the new secret sign every delivery, so you can deploy the new one without missing an event. Pass both while you switch: secret accepts an array.

Get started

Accept payments

Concepts

After a payment

Integrate

1. Add an endpoint

2. Verify and handle events

3. Make your handler safe to repeat

Events

Retries

Signatures in detail

Rotating the secret

​1. Add an endpoint

​2. Verify and handle events

​3. Make your handler safe to repeat

​Events

​Retries

​Signatures in detail

​Rotating the secret

1. Add an endpoint

2. Verify and handle events

3. Make your handler safe to repeat

Events

Retries

Signatures in detail

Rotating the secret