App webhooks

Event catalog

Everything we can send you.

These are the exact events Southbill delivers to app webhook endpoints today. Anything not listed here is never sent — subscribe only to what exists.

How to think about events

The envelope

Every delivery has the same outer shape; only type and data.object differ.

{
  "id": "evt_9f1c2ab34d5e6f70",
  "object": "event",
  "type": "checkout.session.completed",
  "environment": "live",
  "installation": "3f0c…-uuid",
  "created": 1755423672,
  "data": { "object": { "…": "resource payload" } }
}

Delivery headers: Southbill-Signature, Southbill-Event-Id, Southbill-Event-Type, Southbill-Environment, Southbill-Delivery-Attempt.

Checkout

The checkout session is the object your app should treat as the order.

Payments (payment intents)

Lower-level than checkout — use these only if you need the payment view.

Billing

Refunds, disputes and payouts

These arrive as standalone events — no polling required.

Payout events require the restricted payouts:read scope.

Southbill Store (orders & catalogue)

Store events are separate from checkout.session.* on purpose: checkout.session.completed means "money arrived", order.paid means "a Southbill Store order exists and must be fulfilled". Invoice money never appears here — it uses invoice.*.

The order payload is object: "store.order" with source: "store"; id and payment both hold the checkout session ID. Requires the store:read scope.

Lifecycle

Minimal handler

export async function POST(req) {
  const raw = await req.text();
  if (!verifySignature(raw, req.headers.get("southbill-signature"), SECRET)) {
    return new Response("bad signature", { status: 400 });
  }
  const event = JSON.parse(raw);
  if (await seen(event.id)) return new Response("ok");   // dedupe
  await store(event.id);
  switch (event.type) {
    case "checkout.session.completed": await fulfil(event.data.object); break;
    case "checkout.session.refunded":  await refund(event.data.object); break;
    default: break;                                      // ignore unknown types
  }
  return new Response("ok");                             // 2xx within 10s
}

See Signatures & retries.

Event payloads

What each event means and what it carries.

Every delivery uses the same envelope; only type and data.object differ. created is a Unix timestamp in seconds.

{ "id": "evt_9f1c2ab34d5e6f70", "object": "event", "type": "checkout.session.completed",
  "environment": "live", "installation": "3f0c…-uuid", "created": 1755423672,
  "data": { "object": { … } } }

Checkout session payload

All checkout.session.* events carry the same base object, plus a few event-specific fields.

{
  "id": "b6b1…-uuid",
  "object": "checkout.session",
  "status": "complete",
  "environment": "live",
  "amount": 2500,
  "currency": "eur",
  "reference": "cs_2f81c0",
  "metadata": { "order_id": "1042" },
  "payment_intent": "pi_3Nk91x…",
  "setup_intent": null,
  "subscription": null,
  "charge": "ch_3Nk91x…"
}

Event-specific extras

{ "type": "checkout.session.refunded",
  "data": { "object": { "id": "b6b1…", "object": "checkout.session", "status": "complete",
    "amount": 2500, "currency": "eur", "amount_refunded": 500, "fully_refunded": false } } }

Payment intent payloads

payment_intent.succeeded

{ "id": "pi_3Nk91x", "amount": 2500, "amount_received": 2500, "currency": "eur",
  "status": "succeeded", "customer": "cus_8f21", "latest_charge": "ch_3Nk91x",
  "payment_method_types": ["card"], "metadata": { "order_id": "1042" } }

payment_intent.payment_failed replaces amount_received/latest_charge with:

{ "id": "pi_3Nk91x", "amount": 2500, "currency": "eur", "status": "requires_payment_method",
  "customer": null, "failure_code": "card_declined", "decline_code": "insufficient_funds",
  "failure_message": "Your card has insufficient funds.", "metadata": {} }

payment_intent.requires_action and payment_intent.canceled carry the same base fields (id, amount, currency, status, customer, metadata).

Billing payloads

invoice.payment_failed and customer.subscription.deleted carry the processor invoice/subscription object. Always read status before changing entitlements, and treat unknown fields as additive.

Delivery guarantees

At-least-once and unordered. Deduplicate on the event id; when order matters, compare created or re-fetch the object from the App API.

Signatures & retries

Verify every payload, survive every retry.

Signature header

Southbill-Signature: t=1755423672,v1=6f1c…9ab2

Signed payload = "{t}.{raw body}", HMAC-SHA256 with your endpoint secret (whsec_…), hex encoded.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(raw: string, header: string, secret: string, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!Number.isFinite(age) || age > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${parts.t}.${raw}`).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(String(parts.v1 ?? ""));
  return a.length === b.length && timingSafeEqual(a, b);
}

import hashlib, hmac, time

def verify(raw: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    try:
        age = abs(time.time() - int(parts["t"]))
    except (KeyError, ValueError):
        return False
    if age > tolerance:
        return False
    expected = hmac.new(
        secret.encode(), f"{parts['t']}.".encode() + raw, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

<?php
function southbill_verify(string $raw, string $header, string $secret, int $tolerance = 300): bool {
    $parts = [];
    foreach (explode(",", $header) as $p) {
        [$k, $v] = array_pad(explode("=", $p, 2), 2, "");
        $parts[trim($k)] = $v;
    }
    if (!isset($parts["t"], $parts["v1"])) return false;
    if (abs(time() - (int) $parts["t"]) > $tolerance) return false;
    $expected = hash_hmac("sha256", $parts["t"] . "." . $raw, $secret);
    return hash_equals($expected, $parts["v1"]);
}

Verify against the raw body — parsing first and re-serializing breaks the signature.

Rules for your endpoint

1. Answer 2xx within 10 seconds. Do the work asynchronously.
2. Be idempotent: store event.id and drop duplicates.
3. Do not rely on ordering. Compare timestamps or re-fetch the object.
4. Reject requests whose signature fails — never "process anyway and log".

Retries

Failed or slow deliveries retry with exponential backoff for 24 hours: roughly 1 min, 5 min, 30 min, 2 h, 6 h, 12 h. After that the delivery is marked failed and stays visible in the logs for manual replay.

An endpoint failing continuously for 72 hours is auto-disabled and you are notified.

Secret rotation

Rotating issues a second active secret; both validate during a 24-hour overlap so you can deploy without dropped events. Old secrets are then destroyed. Secrets are stored encrypted (AES-GCM) and shown once.

Replay

Any delivery can be replayed from the logs with the original payload — the retry counter and signature timestamp are refreshed.

Testing webhooks

Local development, replays and common failure modes.

Local development

Expose your local server (ngrok, cloudflared) and register the HTTPS URL as a test endpoint. http://localhost is only accepted for OAuth redirects, never for webhooks.

Trigger events

• from the environment's ledger tools (real state changes), or
• with the event simulator (synthetic payloads for any event type).

Read the logs

Each delivery shows request headers, raw body, your response code and body, latency and every retry. Filter by event type or status to find a bad handler quickly.

Common failures

Checklist before launch

• Signature verified against the raw body, with a 5-minute tolerance
• event.id deduplicated for at least 30 days
• Handler returns 2xx in under 10 seconds
• Unknown event types ignored without erroring
• Alerting on delivery failure rate