Handle webhooks

Runledger tells you when something happens that you didn’t directly request: a confirmation window closed, a rule reversed a charge, a dispute deadline is near, an invoice finalized. Register an endpoint with POST /v1/webhook_endpoints and choose the event types you handle.

The payload

Events are thin. They say what happened and to which object, and you fetch the object for its current state:

{
  "id": "whe_0pL3kJ6hGf",
  "object": "webhook_event",
  "type": "outcome_charge.reversed",
  "api_version": "2026-10-18",
  "related_object": {
    "id": "oc_2xK9cL4vRt",
    "object": "outcome_charge",
    "url": "/v1/outcome_charges/oc_2xK9cL4vRt"
  },
  "reason": { "type": "rule" },
  "livemode": false,
  "created_at": "2026-11-04T13:12:09Z"
}

Events about a window, a threshold or a purchase also carry a context that names the customer, member_id, team_id, pool, allowance, spend limit and threshold they are about, so you can write a message without another call. Events that report a share of a window or limit point related_object at the customer’s usage summary.

Fetching the object means an out-of-date event can never overwrite newer state. When the cause was an API request, reason carries its request_id and idempotency_key, so you can match the event to your own call.

Verify deliveries

Deliveries follow the Standard Webhooks specification, so its open-source libraries verify them. Each delivery has three headers:

• webhook-id: unique per event and the same on every retry. Use it to drop duplicates.
• webhook-timestamp: when this attempt was signed. Reject attempts more than five minutes old.
• webhook-signature: v1, followed by a base64 HMAC-SHA256 of id.timestamp.body, keyed with the endpoint’s whsec_ secret.

import express from "express";
import { Webhook } from "standardwebhooks";
const app = express();
const wh = new Webhook(process.env.RUNLEDGER_WEBHOOK_SECRET!);
app.post("/webhooks/runledger", express.raw({ type: "application/json" }), (req, res) => {
  // Throws if the signature or timestamp is wrong.
  const event = wh.verify(req.body, req.headers as Record<string, string>) as {
    type: string;
    related_object: { id: string; object: string };
  };
  // Queue the event, then respond within 15 seconds.
  res.sendStatus(200);
});

Verify against the raw body, before any JSON parsing changes it. While a secret is rotating, deliveries carry two signatures and either one passes.

Delivery

• At least once, so deduplicate on webhook-id.
• In no guaranteed order. Fetch the object instead of relying on order.
• Any 2xx within 15 seconds counts as delivered. Anything else is retried with exponential backoff for three days.
• An endpoint that fails every delivery for five days is disabled automatically, and status becomes disabled. Each endpoint reports last_success_at, last_failure_at, failing_since and disables_at, so you can see a failing endpoint before it is disabled. Set status back to enabled with PATCH /v1/webhook_endpoints/{id} once the endpoint works again.
• Missed events are not replayed automatically. An event that failed all its retries stays failed, and events that happened while an endpoint was disabled are not sent to it when you enable it again. Redeliver is manual and per event: find them with GET /v1/webhook_events?delivery_status=failed (or by endpoint), and send each one with POST /v1/webhook_events/{id}/redeliver. The list keeps the last 30 days, so redeliver within that window.
• POST /v1/test_helpers/webhook_endpoints/{id}/send_event sends a signed sample event to one endpoint in the sandbox, so you can test a handler and its signature check.
• GET /v1/webhook_events lists the last 30 days, so you can catch up after an outage, and POST /v1/webhook_events/{id}/redeliver sends one event again, to one endpoint or to every enabled endpoint subscribed to its type. Nothing redelivers for you. Each event has a delivery_status of pending, succeeded or failed, and the list filters by delivery_status and by endpoint.

Event types

New types may be added; subscribe only to the ones you handle.

See also

• Going live shows how to wire up webhooks and disputes.
• Outcome settlement explains the lifecycle the events report.