Webhooks

# A webhook: another service (your payment provider) calls this URL. The
# sender has no backd session, so `invoke` must allow anonymous callers and
# the function itself is the only check: it verifies the signature.
#
# `admin: true` because marking an order paid is not something a customer
# rule allows. The signing secret is set with
#   backd secret set --realm workshop --database main --name PAYMENT_WEBHOOK_SECRET
mode: webhook
invoke: "true"
admin: true
secrets: [PAYMENT_WEBHOOK_SECRET]

// payment_webhook: handles "payment.succeeded" events from a payment
// provider. The provider signs the raw body (x-signature: sha256=<hex>) and
// retries any delivery it didn't get a 2xx for, so the same event can
// arrive more than once.
import { verifySignature } from "../lib/signature.ts";
import type { Context } from "../lib/types.ts";

type PaymentEvent = { id: string; type: string; order_id: string };

export default async function handler(ctx: Context) {
  // 1. Verify the sender, against the exact bytes it signed.
  const { body, headers } = ctx.request;
  if (!(await verifySignature(ctx.secrets.PAYMENT_WEBHOOK_SECRET, body, headers["x-signature"]))) {
    return { status: 400, body: "invalid signature" };
  }

  // 2. Deduplicate by the provider's own event id: the unique index on
  //    events.event_id refuses a second insert with a 409.
  const event = JSON.parse(body) as PaymentEvent;
  const db = ctx.admin.db("main");
  try {
    await db.collection("events").create({ event_id: event.id, type: event.type, order_id: event.order_id });
  } catch (err) {
    if ((err as { status?: number }).status === 409) return { status: 200, body: "already processed" };
    throw err;
  }

  // 3. Handle it.
  if (event.type === "payment.succeeded") {
    try {
      await db.collection("orders").patch(event.order_id, { status: "paid" });
    } catch (err) {
      if ((err as { status?: number }).status === 404) return { status: 404, body: "unknown order" };
      throw err;
    }
  }
  return { status: 200, body: "ok" };
}

// HMAC-SHA256 signatures for webhooks: the sender signs the raw request
// body with a secret you share, and sends it as `x-signature: sha256=<hex>`.
const encoder = new TextEncoder();

async function hmacHex(secret: string, body: string): Promise<string> {
  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
  const mac = await crypto.subtle.sign("HMAC", key, encoder.encode(body));
  return [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("");
}

/** What a sender puts in the header (used by tests and by the docs' curl example). */
export async function sign(secret: string, body: string): Promise<string> {
  return `sha256=${await hmacHex(secret, body)}`;
}

/** True when `header` is the signature of `body` under `secret`. Compares in constant time. */
export async function verifySignature(secret: string, body: string, header: string | undefined): Promise<boolean> {
  if (!header) return false;
  const expected = encoder.encode(await sign(secret, body));
  const given = encoder.encode(header);
  if (expected.length !== given.length) return false;
  let diff = 0;
  for (let i = 0; i < expected.length; i++) diff |= expected[i] ^ given[i];
  return diff === 0;
}

backd secret set --realm workshop --database main --name PAYMENT_WEBHOOK_SECRET   # the shared secret
BODY='{"id": "evt_1", "type": "payment.succeeded", "order_id": "d3c9ljp8hc2g00b6s1m0"}'
SIG="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac 'whsec_test' | sed 's/^.* //')"
curl -X POST https://api.example.com/v1/workshop/main/_func/payment_webhook -H "x-signature: $SIG" -d "$BODY"
# → 200 ok           (the same request again: 200 already processed; a wrong signature: 400 invalid signature)