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

1
import { Webhook } from "svix";
2
import { createServer } from "node:http";
3
4
const SECRET = process.env.PIVOTAL_WEBHOOK_SECRET!;
5
const wh = new Webhook(SECRET);
6
7
createServer((req, res) => {
8
  if (req.method !== "POST") return res.writeHead(405).end();
9
10
  let body = "";
11
  req.on("data", (chunk) => (body += chunk));
12
  req.on("end", () => {
13
    const headers = {
14
      "svix-id": req.headers["svix-id"] as string,
15
      "svix-timestamp": req.headers["svix-timestamp"] as string,
16
      "svix-signature": req.headers["svix-signature"] as string,
17
    };
18
    try {
19
      const event = wh.verify(body, headers) as { type: string; id: string };
20
      console.log(`${event.type} · ${event.id}`);
21
      res.writeHead(200).end("ok");
22
    } catch {
23
      res.writeHead(401).end("invalid signature");
24
    }
25
  });
26
}).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