Webhooks

Les webhooks de messages contiennent un tableau results : une même requête peut porter plusieurs événements ; les événements d’appel arrivent un par requête. Un bon handler vérifie que la requête vient de Pulsr, enregistre ou met en file les événements, et répond 200 immédiatement.

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 });}

• Utilisez HTTPS. Les URL de webhook doivent être accessibles publiquement en HTTPS, avec un certificat valide.
• Ajoutez un secret dans l’URL. Générez une longue valeur aléatoire, ajoutez-la en paramètre (https://yourapp.com/webhooks/pulsr?token=…) et comparez-la en temps constant, comme dans le handler ci-dessus. Faites-la tourner comme n’importe quel secret.
• Ne faites jamais confiance aveuglément au contenu. Retrouvez le messageId dans vos propres données avant d’agir sur un événement.

• Répondez vite. Renvoyez un statut 2xx dès que les événements sont enregistrés. Faites le travail long (base de données, e-mails, appels à vos propres API) dans une tâche en arrière-plan.
• Attendez-vous à des doublons. Si votre endpoint expire ou échoue, le même événement peut être renvoyé. Rendez le traitement idempotent en vous appuyant sur le messageId (ou le callId pour la voix) et le statut.
• Ne comptez pas sur l’ordre. Les événements peuvent arriver dans le désordre. Comparez les horodatages comme doneAt avant de remplacer un statut récent par un plus ancien.

Pulsr a besoin d’une URL publique pour joindre votre machine. Lancez un tunnel comme ngrok http 3000 ou cloudflared tunnel --url http://localhost:3000, puis utilisez l’adresse HTTPS affichée comme URL de webhook.