Send and receive webhooks

network:
  allow: [hooks.partner.dev]      # the hosts webhooks.emit may call
webhooks:
  secret: secret:WEBHOOK_SIGNING_KEY    # signs the webhooks you send
  retries: { max: 8, window: 24h }
  inbound:
    github: { preset: github, secret: secret:GITHUB_WEBHOOK_SECRET, path: /api/webhooks/github }

import { jobs, webhooks } from "mainsdk";

export const POST = webhooks.receive("github", async (body, meta) => {
  // body is the parsed JSON; meta.id is GitHub's delivery id
  await jobs.run("deploys.record", { delivery: meta.id, payload: body }, { idempotencyKey: meta.id });
});

import { webhooks } from "mainsdk";

export async function notifyPartner(order: { id: string }) {
  return webhooks.emit(
    "https://hooks.partner.dev/in",
    { type: "order.shipped", data: { orderId: order.id } },
    { idempotencyKey: `order.shipped:${order.id}` },
  );
}

npx mainsdk webhooks list --json
npx mainsdk webhooks replay <id>
npx mainsdk webhooks replay <id> --same-id   # keep the delivery id, to test the duplicate check

import { describe, it } from "node:test";
import { createHmac } from "node:crypto";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";

const secrets = {
  WEBHOOK_SIGNING_KEY: `whsec_${Buffer.from("signing-key-bytes").toString("base64")}`,
  GITHUB_WEBHOOK_SECRET: "gh-secret",
};

describe("webhooks", () => {
  it("webhooks-jobs AC3 and AC7: refuses a forged delivery and runs a duplicate once", async () => {
    const app = createTestApp({ main: "./main.yaml", secrets });
    let ran = 0;
    const POST = app.webhooks.receive("github", () => void ran++);
    const body = JSON.stringify({ action: "opened" });
    const post = (key: string) =>
      POST(new Request("http://localhost/api/webhooks/github", {
        method: "POST",
        body,
        headers: {
          "x-hub-signature-256": `sha256=${createHmac("sha256", key).update(body).digest("hex")}`,
          "x-github-delivery": "gh-1",
        },
      }));
    assert.equal((await post("wrong")).status, 400);
    assert.equal(ran, 0);
    assert.equal((await post("gh-secret")).status, 200);
    assert.equal((await post("gh-secret")).status, 200);
    assert.equal(ran, 1);
  });

  it("webhooks-jobs AC2: retries a failing endpoint with the same webhook-id", async () => {
    let calls = 0;
    const app = createTestApp({
      main: "./main.yaml",
      secrets,
      respond: () => new Response(null, { status: ++calls < 4 ? 500 : 200 }),
    });
    const id = await app.webhooks.emit("https://hooks.partner.dev/in", { type: "order.shipped", data: { orderId: "o1" } });
    for (const wait of ["10s", "6m", "31m"]) await app.clock.tick(wait);   // the retry schedule
    const ids = new Set(app.sent.map((r) => r.headers.get("webhook-id")));
    assert.equal(app.sent.length, 4);
    assert.equal(ids.size, 1);
    const delivery = await app.webhooks.delivery(id);
    assert.equal(delivery?.status, "delivered");
    assert.equal(delivery?.attempts?.length, 4);
  });
});

npx mainsdk check
node --test app/webhooks.test.ts

Goal: receive <provider> webhooks safely and send signed webhooks to <partner host>.
Touch: main.yaml (webhooks.inbound, webhooks.secret, network.allow), one route file that exports webhooks.receive(...), the module that calls webhooks.emit(), one test.
Do: use the provider's preset; keep every secret as a secret: reference; hand slow work to jobs.run() keyed by meta.id.
Do not: parse or verify signatures by hand, add your own dedupe table, put a secret literal in main.yaml, or add the partner's host to network.allow without telling the owner.
Verify: npx mainsdk check, then node --test on the webhook test file.
Stop and ask if: the provider is not one of the presets, or its signing secret is not available yet.