Webhooks

When something happens in a project — a user is deleted, a file is uploaded, a secret changes, an email bounces — the platform POSTs an event to each of the project's webhook endpoints that takes its type, signed with that endpoint's secret. palbase/server checks the signature: verifyWebhookRequest(request, secret) answers the event, or throws. A palbase/backend app does not call it at all — its @On handlers receive the events already checked (see Event Hooks).

Quick example

// server.ts
import { verifyWebhookRequest, WebhookSignatureError } from "palbase/server";

const secret = process.env.PALBASE_WEBHOOK_SECRET!; // whsec_…, shown once when the endpoint was made
const handled = new Set<string>();

export async function handle(request: Request): Promise<Response> {
  let event;
  try {
    event = await verifyWebhookRequest<{ user_id?: string }>(request, secret);
  } catch (e) {
    if (e instanceof WebhookSignatureError) return new Response(e.code, { status: 401 });
    throw e;
  }
  // A delivery may come twice: the event's id says it is the same one.
  if (handled.has(event.id)) return new Response(null, { status: 204 });
  if (event.type === "user.deleted") {
    console.log(`forget everything about ${event.data.user_id}`);
  }
  handled.add(event.id);
  return new Response(null, { status: 204 });
}

Any 2xx is delivery. Anything else — another status, a timeout, a refused connection — and the platform sends the event again.

Endpoints

An endpoint is an https URL on the public internet and the event types it takes — up to 50 of them, each dotted lowercase words such as user.deleted; an endpoint that names none takes every type. A project has 5 endpoints at most, besides the ones the platform keeps for its machines. When an endpoint is made, its secret (whsec_ and 64 hex characters) is answered once; keep it in the receiving server's secrets.

Manage a project's endpoints in Studio, under an environment's Settings › Webhooks: add an endpoint (its secret is shown once, with a copy button), change its address or events, or delete it. Reading the list is open to the organization's members; adding, changing and deleting are an admin's — a person, or an admin access token. Each endpoint shows who made it: a person, an access token or an environment token, by the name it had then. An endpoint stays when the token that made it is deleted. Palbase's own environment is shown read-only. A palbase/backend app on a machine needs none of this: the platform gives the machine its PALBASE_WEBHOOK_SECRET and keeps an endpoint for exactly the events its app takes, listed as the machine's — not changed or deleted from here, and gone with the machine (Event Hooks).

The CLI does the same:

palbase webhooks:create https://api.example.com/palbase --events user.deleted,file.uploaded --secret-to RECEIVER_WEBHOOK_SECRET
palbase webhooks:list
palbase webhooks:update <id> --events user.deleted
palbase webhooks:delete <id>

--secret-to keeps the new endpoint's secret in the environment's secrets (production, or development with --dev) instead of printing it, so a receiver that is itself a machine of the environment reads it by name. See the CLI reference.

Failed deliveries

A delivery is tried 12 times, the wait growing up to five minutes between tries. When the endpoint still has not taken it, Palbase gives up and keeps the delivery for 30 days under Settings › Webhooks › Failed deliveries: the event, the endpoint, how many times it was tried and why the last try failed. Redeliver sends the same event, with the same Palbase-Event-Id and body, to that endpoint again within seconds, signed afresh, as Stripe's Resend does. Your receiver already handles an event more than once by its id, so a redelivery is safe. Members read the list; an admin redelivers, and the redelivery is written to the organization's audit log. Studio's API does the same: GET /v1/environments/{ref}/webhooks/deliveries?failed=true and POST /v1/environments/{ref}/webhooks/deliveries/{id}/redeliver. A delivery whose endpoint was deleted is sent nowhere (409 endpoint_gone).

What a delivery is

A delivery is a POST with a JSON body — the event — and three headers:

{
  "id": "6f2c1c9e-…",
  "type": "file.uploaded",
  "project_id": "2b7d…",
  "created_at": "2026-10-08T09:41:22Z",
  "data": { "bucket": "avatars", "path": "usr_123/face.png", "size": 48211, "content_type": "image/png", "owner_id": "usr_123" }
}

The platform waits 10 seconds for an answer, follows no redirect, and tries an event up to 12 times, waiting 1 s, 2 s, 4 s … up to five minutes between attempts. One project's slow or silent receiver holds back only that project's events.

Delivery is at least once. An event that reached your endpoint may be sent again — a retry after a timeout your server answered too late, or the platform's sender starting again — so key the work on the event's id, not on its arrival. An event is never dropped because an endpoint was down for a while: it is retried until it is taken or its attempts run out.

The events

The modules' contracts say which of their operations emit which event; each is noted on the operation (for example, PUT /storage/buckets/{bucket}/objects/{path} "Emits file.uploaded").

Checking a delivery

The signature is an HMAC of the body exactly as it arrived — the bytes, before any JSON parsing. A parsed and re-serialised body is a different string and never verifies, so read the raw body first.

Each throws a WebhookSignatureError whose code says why:

verifyWebhook takes only an endpoint secret (whsec_…): an API key passed by mistake is a TypeError, not a check that quietly fails.

// app/api/palbase/route.ts
import { verifyWebhook, WebhookSignatureError } from "palbase/server";

export async function POST(request: Request): Promise<Response> {
  const body = await request.text(); // the raw body, before anything parses it
  try {
    const event = await verifyWebhook({
      secret: process.env.PALBASE_WEBHOOK_SECRET!,
      signature: request.headers.get("palbase-signature"),
      body,
    });
    console.log(event.type, event.id);
    return new Response(null, { status: 204 });
  } catch (e) {
    if (e instanceof WebhookSignatureError) return new Response(e.code, { status: 401 });
    throw e;
  }
}

The platform's own calls to a machine

The platform signs what it asks of a machine the same way, with the key it starts every machine with in PALBASE_PLATFORM_SECRET: the crons' and tasks' lists and calls (GET /_palbase/crons, POST /_palbase/crons/<name>, GET /_palbase/tasks, POST /_palbase/tasks/<name>). Those paths are reached only by the platform: a request from outside whose path names them never gets to the machine. A program that serves them checks the call with verifySignature, whose body is the request's (empty for a GET). See Machines.

Related

• Event Hooks — @On handlers in a palbase/backend app
• Backend Webhooks — a third party's deliveries (Stripe, GitHub, …) to a palbase/backend app, with @Webhook
• Server SDK Overview — createServer, refusals and retries
• Storage — what emits file.uploaded, file.deleted and file.moved
• Secrets — where a receiving server keeps its endpoint secret