Webhooks

webhooks sends signed webhooks with retries and a delivery log, and verifies incoming ones before your handler runs. Use it when your app notifies other systems or Stripe or GitHub calls you.

webhooks:
  driver: builtin
  secret: secret:WEBHOOK_SIGNING_KEY
  retries: { max: 8, window: 24h }

import { webhooks } from "mainsdk";

export const POST = webhooks.receive("github", async (event) => {
  await handlePush(event.data);      // runs only after the signature is checked
});

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

const yaml = `schema: 1
project: prj_test
webhooks:
  inbound:
    partner: { preset: standard, secret: secret:PARTNER_SECRET, path: /api/hooks/partner }
`;
const secret = `whsec_${Buffer.from("partner-secret-bytes").toString("base64")}`;

describe("partner webhooks", () => {
  it("webhooks-jobs AC3 refuses a bad signature and a stale timestamp, and AC7 runs a duplicate once", async () => {
    const app = createTestApp({ yaml, secrets: { PARTNER_SECRET: secret } });
    let ran = 0;
    const POST = app.webhooks.receive("partner", () => void ran++);
    const body = JSON.stringify({ type: "partner.updated", data: {} });
    const now = Math.floor(app.clock.now() / 1000);
    const post = (key: string, id: string, at: number) =>
      POST(new Request("http://localhost/api/hooks/partner", {
        method: "POST",
        body,
        headers: signHeaders([key], id, { timestampSeconds: at, body }),
      }));

    const wrongKey = `whsec_${Buffer.from("not-the-secret").toString("base64")}`;
    assert.equal((await post(wrongKey, "msg_1", now)).status, 400);
    assert.equal((await post(secret, "msg_2", now - 360)).status, 400);
    assert.equal(ran, 0);

    assert.equal((await post(secret, "msg_3", now)).status, 200);
    assert.equal((await post(secret, "msg_3", now)).status, 200);
    assert.equal(ran, 1);
  });
});

webhooks:
  driver: builtin

Quick start

Declare the inbound endpoint and its secret, then receive it in a route handler.

webhooks:
  inbound:
    github: { preset: github, secret: secret:GITHUB_WEBHOOK_SECRET, path: /api/webhooks/github }

import { webhooks } from "mainsdk";

declare function recordPush(body: unknown, deliveryId: string): Promise<void>;

export const POST = webhooks.receive("github", async (body, meta) => {
  await recordPush(body, meta.id);   // your code; runs only after the signature is checked
});

A request with a wrong signature or a stale timestamp never reaches your handler. It gets 400 with MAIN-HOOK-0002 and is logged without its body. The handler gets the parsed body and meta: { id, name, preset, headers, raw, replay }, where id is the provider's delivery id.

Configuration

webhooks:
  secret: secret:WEBHOOK_SIGNING_KEY    # signs outbound deliveries from webhooks.emit
  retries: { max: 8, window: 24h }      # attempts before giving up, and the time they may span
  inbound:                              # every inbound endpoint the app serves
    stripe: { preset: stripe, secret: secret:STRIPE_WEBHOOK_SECRET, path: /api/webhooks/stripe }
    github: { preset: github, secret: [secret:GITHUB_HOOK_NEW, secret:GITHUB_HOOK_OLD], path: /api/webhooks/github }
    twilio: { preset: twilio, secret: secret:TWILIO_AUTH_TOKEN, path: /api/webhooks/twilio, public-url: https://app.pinecart.dev }
network:
  allow: [hooks.partner.dev]            # hosts webhooks.emit may call

webhooks.receive("github", handler) with no inbound entry uses the preset's defaults and the secret secret:GITHUB_WEBHOOK_SECRET. A name that is neither a declared entry nor a preset fails with MAIN-HOOK-0003.

What you get

• Outbound, webhooks.emit() signs each delivery per Standard Webhooks, retries with backoff and records every attempt in a delivery log.
• Inbound, webhooks.receive() checks the signature and timestamp over the raw body before your handler runs.
• Replays older than 5 minutes are refused, and your handler runs once even when the sender delivers twice.
• Presets for Stripe, GitHub, Razorpay and any Standard Webhooks sender.
• Customer-managed endpoints, and mainsdk webhooks replay to re-run a recorded delivery in development.

Inbound presets

Each preset verifies the signature over the exact raw body bytes with a constant-time compare, then passes the provider's delivery id to the idempotency record so a duplicate calls your handler once.

A preset with no replay window relies on the duplicate check alone; mainsdk info marks it "no replay window". For Stripe and Razorpay payment events, prefer pay.on(), which reads pay.<provider>.webhook and gives you typed payment events.

Examples

Emit a signed webhook with retries

import { webhooks } from "mainsdk";

export async function notifyPartner(order: { id: string }) {
  const deliveryId = await webhooks.emit(
    "https://hooks.partner.dev/in",
    { type: "order.shipped", data: { orderId: order.id } },
    { idempotencyKey: `order.shipped:${order.id}` },
  );
  return deliveryId;   // the delivery is queued; attempts run in the background
}

emit returns the delivery id once the delivery is queued. Each request carries webhook-id, webhook-timestamp and webhook-signature (v1,<base64>), which verify with any Standard Webhooks library. The body is a CloudEvents envelope. If the endpoint answers anything but 2xx, the same webhook-id is sent again after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours and 10 hours, up to retries.max attempts inside retries.window. Leave out idempotencyKey and one is made from the endpoint and the event. The URL goes through the network layer, so its host must be in network.allow. Read a delivery with webhooks.delivery(id); it lists each attempt with its status and response status, never a body.

Duplicates run your handler once

Senders retry. If the same event (same provider delivery id) arrives twice, your handler runs once and both requests get 200 with { "received": true }. You do not need your own dedupe table. If your handler throws, the sender gets a 500 and the delivery is not marked done, so its retry runs your handler again.

import { webhooks } from "mainsdk";

declare function recordDeploy(body: unknown): Promise<void>;

export const POST = webhooks.receive("github", async (body) => {
  await recordDeploy(body);   // safe: a redelivery of this event won't call the handler again
});

Keep handlers short. Hand slow work to jobs.run() so the sender gets its 200 quickly. A handler may return a Response (for example TwiML for Twilio); it is sent for the first delivery.

Replay a delivery in development

Under mainsdk dev, every inbound delivery is recorded in .mainsdk/ with its verification result, for 7 days or the last 500 deliveries. Nothing is recorded in any other environment.

pnpm mainsdk webhooks list --json          # recorded deliveries, newest first
pnpm mainsdk webhooks replay <id>          # run your handler again with a new delivery id
pnpm mainsdk webhooks replay <id> --same-id   # keep the id, to test the duplicate check

A replay is signed with a local dev key that only a dev environment accepts from the loopback address. Outside dev, or with no dev server running, it exits 2 with MAIN-HOOK-0012.

Let your customers register endpoints

For endpoints your customers manage, the current tenant gets its own list: webhooks.endpoints.create({ url, events }) returns a whsec_ secret once, and webhooks.send(type, data) queues one signed delivery to every enabled endpoint subscribed to type. The other calls are endpoints.list, update, delete, rotate, test, deliveries and redeliver. Every webhooks.endpoints call needs the webhooks.manage permission, the URL must be public https and is checked again at every connect, and an endpoint that keeps failing is disabled after disable-after failures. List the event types tenants may subscribe to under webhooks.endpoints.events.

webhooks:
  endpoints:
    events: [order.created, order.shipped]
    max-per-tenant: 20
    disable-after: { failures: 50, for: 5d }
    keep-deliveries: 30d

These calls need tenancy and access rules set up; see the spec's customer-managed endpoints section for the full contract and the errors MAIN-HOOK-0004 to MAIN-HOOK-0010.

Errors and checks

Errors are MainError values that serialise as RFC 9457 problem details with a code, a fix and a docs link.

Customer endpoint errors are MAIN-HOOK-0004 (URL refused), 0005 (too many endpoints), 0006 (event type not allowed), 0007 (endpoint disabled after failures), 0008 (test or redeliver to a disabled endpoint), 0009 (not found in this tenant) and 0010 (needs webhooks.manage). An endpoint that keeps failing is retried up to retries.max within retries.window; every attempt is in the delivery log.

Swapping drivers

Outbound webhooks are stateless actions, so a driver swap needs no data migration. svix is the planned second driver; your webhooks.emit() and webhooks.receive() calls stay the same when it ships.

Testing

Call your receive handler with a plain Request signed by signHeaders to prove a forged or stale delivery never reaches your code, and a duplicate runs it once.

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

const yaml = `schema: 1
project: prj_test
webhooks:
  inbound:
    partner: { preset: standard, secret: secret:PARTNER_SECRET, path: /api/hooks/partner }
`;
const secret = `whsec_${Buffer.from("partner-secret-bytes").toString("base64")}`;

describe("partner webhooks", () => {
  it("webhooks-jobs AC3 refuses a bad signature and a stale timestamp, and AC7 runs a duplicate once", async () => {
    const app = createTestApp({ yaml, secrets: { PARTNER_SECRET: secret } });
    let ran = 0;
    const POST = app.webhooks.receive("partner", () => void ran++);
    const body = JSON.stringify({ type: "partner.updated", data: {} });
    const now = Math.floor(app.clock.now() / 1000);
    const post = (key: string, id: string, at: number) =>
      POST(new Request("http://localhost/api/hooks/partner", {
        method: "POST",
        body,
        headers: signHeaders([key], id, { timestampSeconds: at, body }),
      }));

    const wrongKey = `whsec_${Buffer.from("not-the-secret").toString("base64")}`;
    assert.equal((await post(wrongKey, "msg_1", now)).status, 400);
    assert.equal((await post(secret, "msg_2", now - 360)).status, 400);
    assert.equal(ran, 0);

    assert.equal((await post(secret, "msg_3", now)).status, 200);
    assert.equal((await post(secret, "msg_3", now)).status, 200);
    assert.equal(ran, 1);
  });
});

For outbound deliveries, pass respond to createTestApp to answer the requests webhooks.emit() sends, read them from app.sent, and move through the retry schedule with await app.clock.tick("6m").

Security and privacy

• Outbound deliveries are signed per Standard Webhooks, so receivers can verify them with any standard library.
• Inbound signatures and timestamps are checked over the raw body before your code runs; replays outside the window are refused and logged without the body.
• Signing keys are secret: references and never appear in code or logs. A literal secret in main.yaml fails mainsdk check.
• Inbound endpoints appear in mainsdk discover (kind webhook-inbound). Listing them in the seal and mainsdk seal diff is planned.
• The delivery log keeps status, response status and duration for each attempt, never request or response bodies.
• Delivery is at least once with idempotent effects; exactly-once delivery across providers is not promised.

FAQ

Should I use webhooks.receive("stripe", …) or pay.on() for payments? Use pay.on() for payment events; it gives you typed payment events on the same verification.

What do I do when the sender's handler call times out? Return fast. Hand slow work to jobs.run() from your handler.

Do I get a delivery log in production? Yes, the delivery log is part of webhooks.emit() on every plan.

What is not decided yet? Whether the delivery log moves with a driver swap, since only the built-in engine exists today.

Reference

Development replay helpers

mainsdk webhooks is built on these functions. They read and write files under the project's .mainsdk/ folder, and they're exported for tools that need the same recordings.

Next

• Events and background jobs: move slow work out of the handler.
• Send and receive webhooks: the same calls as a walkthrough.
• Payments: verified payment webhooks with pay.on().
• Secrets: store signing keys.