Webhooks

Receive every payout and refund transition, signed and verifiable.

Webhooks are how you find out what happened to a payout. You should not have to poll the API for state at all.

You register one HTTPS URL for your account, and every event is signed with a secret only you and we hold. See Webhook events for the full catalogue.

Register your endpoint

curl -X PUT "$SPENDIN_BASE_URL/v1/webhooks/config" \
  -H "X-API-Key: $SPENDIN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "webhook_url": "https://merchant.example.com/webhooks/spendin" }'

The response contains your signing secret, prefixed whsec_.

The secret is returned once, when you set the URL or rotate it. It is never retrievable afterwards — GET /v1/webhooks/config only tells you whether one exists. Store it in your secrets manager before you discard the response.

The URL must be HTTPS. Plain HTTP is rejected except for localhost and 127.0.0.1, allowed for local development. An invalid URL returns 400 WEBHOOK_URL_INVALID.

Requires the webhooks:manage scope.

Per-payout override

Set notification_url on an individual payout and that payout’s events go there instead of your default URL. Your tenant secret signs both, so verification does not change.

Useful for routing a specific payout’s events to a different consumer without standing up a second account. Everything else still goes to the default.

Verify every delivery

Each request carries these headers:

Header	Value
X-Spendin-Signature	t=<unix_timestamp>,v1=<hmac_sha256_hex>
X-Spendin-Timestamp	The same unix timestamp
X-Spendin-Event	The event_type, e.g. payout.successful
X-Spendin-Delivery	Delivery job ID, useful in support requests

The signature is an HMAC-SHA256 over <timestamp>.<raw_request_body>, keyed with your signing secret.

import { createHmac, timingSafeEqual } from 'crypto';

function verifySignature(
  raw_body: string,          // the exact bytes received — never a re-serialised object
  signature_header: string,
  signing_secret: string,
  tolerance_seconds = 300,
): boolean {
  const parts = Object.fromEntries(
    signature_header.split(',').map((p) => p.split('=')),
  );
  const timestamp = parseInt(parts.t, 10);

  // Reject stale deliveries — blocks replay of a captured request
  if (Math.abs(Date.now() / 1000 - timestamp) > tolerance_seconds) return false;

  const expected = createHmac('sha256', signing_secret)
    .update(`${timestamp}.${raw_body}`, 'utf8')
    .digest('hex');

  const received = Buffer.from(parts.v1);
  const computed = Buffer.from(expected);

  // Constant-time comparison — a plain === leaks the secret via timing
  return received.length === computed.length && timingSafeEqual(received, computed);
}

Verify against the raw request body, before any JSON parsing. Parsing and re-serialising changes whitespace and key order, and the signature will never match. In Express, capture it with express.json({ verify: (req, _res, buf) => { req.raw_body = buf.toString(); } }).

Reject anything that fails verification. An unverified request is not from us.

If no secret is configured for your account, deliveries are sent unsigned — the signature headers are simply absent. Treat a missing X-Spendin-Signature as a failure in production rather than as “nothing to check”, and confirm GET /v1/webhooks/config reports a secret before you go live.

Responding

Return any 2xx, quickly. Anything else — or no response within 10 seconds — counts as a failure.

Do your real work asynchronously: acknowledge first, process after. A handler that runs a slow database write inline will eventually time out and cause duplicate deliveries.

Retries

Failed deliveries are retried up to 5 attempts total (the first attempt plus four retries), with exponential backoff starting at 10 seconds.

Every attempt is logged, whether it succeeded or not. After the fifth the delivery is marked DEAD and not retried again.

There is no replay endpoint. A DEAD delivery is not resent, so an endpoint that is down for long enough will permanently miss events.

Recover by reading state back: GET /v1/payouts with a created_at filter on your side, or GET /v1/webhooks/deliveries to see exactly what was missed. This is why the status timeline is the authoritative history and webhooks are the notification.

Idempotency on your side

The same event may be delivered more than once. Use event_id as the dedupe key — it is stable across every retry.

if (await events.exists(payload.event_id)) return res.sendStatus(200);
await events.record(payload.event_id);
await queue.enqueue(payload);
res.sendStatus(200);

Do not deduplicate on created_at or on arrival order. Deliveries can arrive out of order; treat status in the payload as the truth and ignore an event that would move a payout backwards from where your record already is.

Debugging

curl "$SPENDIN_BASE_URL/v1/webhooks/deliveries?limit=20" \
  -H "X-API-Key: $SPENDIN_API_KEY"

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "payout_id": "a3f1c2d4-...",
      "event_id": "d9c8b7a6-...",
      "event_type": "payout.successful",
      "attempt_number": 2,
      "target_url": "https://merchant.example.com/webhooks/spendin",
      "response_status": 200,
      "status": "SUCCESS",
      "failure_reason": null,
      "created_at": "2026-08-16T14:39:12.000Z"
    }
  ],
  "meta": { "next_cursor": null, "has_more": false, "limit": 20 }
}

Delivery status	Meaning
SUCCESS	Your endpoint returned 2xx
FAILED	This attempt failed; a retry is scheduled
DEAD	All five attempts exhausted — not retried again

This is the fastest way to tell “we never sent it” from “your endpoint rejected it”. failure_reason carries the HTTP status or the transport error — a timeout, a DNS failure, a TLS problem.

Rotating the secret

curl -X POST "$SPENDIN_BASE_URL/v1/webhooks/config/rotate-secret" \
  -H "X-API-Key: $SPENDIN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

The new secret is returned once and takes effect immediately — there is no grace window during which the old one still verifies.

Deploy the new secret to your handler within the same change, or in-flight deliveries signed with the new secret will fail verification against your old one. If you need zero-gap rotation, have your handler accept either secret for a short period, then drop the old one.