Webhooks

Message webhooks carry a results array, so one request can hold several events; call events arrive one per request. A good handler checks that the request comes from Pulsr, stores or queues the events, and answers 200 straight away.

import { timingSafeEqual } from "node:crypto";const SECRET = process.env.PULSR_WEBHOOK_SECRET!;function isFromPulsr(req: Request) {  const token = new URL(req.url).searchParams.get("token") ?? "";  return (    token.length === SECRET.length &&    timingSafeEqual(Buffer.from(token), Buffer.from(SECRET))  );}export async function POST(req: Request) {  if (!isFromPulsr(req)) return new Response(null, { status: 401 });  const { results } = await req.json();  for (const event of results) {    // Queue the work and answer fast; deduplicate on event.messageId    await queue.push(event);  }  return new Response(null, { status: 200 });}

• Use HTTPS. Webhook URLs must be publicly reachable over HTTPS with a valid certificate.
• Add a secret to the URL. Generate a long random value, add it as a query parameter (https://yourapp.com/webhooks/pulsr?token=…) and compare it in constant time, as in the handler above. Rotate it like any other secret.
• Never trust the payload blindly. Look the messageId up in your own records before acting on an event.

• Answer fast. Return a 2xx status as soon as the events are safely stored. Do slow work (database updates, emails, your own API calls) in a background job.
• Expect duplicates. If your endpoint times out or fails, the same event can be sent again. Make processing idempotent by keying on messageId (or callId for voice) and the status.
• Do not rely on order. Events can arrive out of order. Compare timestamps such as doneAt before overwriting a newer status with an older one.

Pulsr needs a public URL to reach your laptop. Run a tunnel such as ngrok http 3000 or cloudflared tunnel --url http://localhost:3000, then use the HTTPS address it prints as your webhook URL.