Webhooks quickstart

Receive your first Pivotal event on a local server in under five minutes. The flow: tunnel a local port to a public URL, register the URL as a Pivotal webhook endpoint, send a test event from the dashboard, verify the signature on receipt.

• Node 20+ or Python 3.10+
• An admin role on your Pivotal workspace (you’ll need to register the endpoint)
• A local tunnel — ngrok, Cloudflare tunnel, or Tailscale Funnel

import { Webhook } from "svix";
import { createServer } from "node:http";
const SECRET = process.env.PIVOTAL_WEBHOOK_SECRET!;
const wh = new Webhook(SECRET);
createServer((req, res) => {
  if (req.method !== "POST") return res.writeHead(405).end();
  let body = "";
  req.on("data", (chunk) => (body += chunk));
  req.on("end", () => {
    const headers = {
      "svix-id": req.headers["svix-id"] as string,
      "svix-timestamp": req.headers["svix-timestamp"] as string,
      "svix-signature": req.headers["svix-signature"] as string,
    };
    try {
      const event = wh.verify(body, headers) as { type: string; id: string };
      console.log(`${event.type} · ${event.id}`);
      res.writeHead(200).end("ok");
    } catch {
      res.writeHead(401).end("invalid signature");
    }
  });
}).listen(8787, () => console.log("listening on :8787"));

bun webhook-receiver.ts
# or: ts-node webhook-receiver.ts

Pick whichever tunnel you already use. ngrok example:

ngrok http 8787
# Forwarding  https://aurora-1234.ngrok.app -> http://localhost:8787

Copy the https:// URL.

1. Open Admin → Developer → Webhooks
2. Click Add endpoint
3. Paste the ngrok URL
4. Pick customer.created and task.completed for now
5. Copy the signing secret and export PIVOTAL_WEBHOOK_SECRET=… in your receiver shell

In the Webhooks dashboard, click your endpoint, then Send test event. Pick customer.created. Your terminal logs the event type + id, the dashboard shows a green check, and the Logs tab records the delivery with the full payload.

• Event envelope — the standard shape of every payload
• Signature verification — what the Svix SDK does under the hood
• Retries and backoff — what happens when your server returns non-2xx