Retour au quickstartWebhook basics

Recevoir et vérifier les événements

Les webhooks transmettent l’état réel des messages sans polling. Ce guide décrit la création d’un endpoint, la signature et le payload livré par la plateforme avec le SDK JavaScript officiel.

Règles de base

Les callbacks utilisent une signature HMAC-SHA256 sur `timestamp.payload`. Le timestamp et la signature arrivent dans les headers HTTP.

Retourner un 2xx rapidement quand le callback est traité.
Traiter `x-coussema-event` comme la source de vérité pour le type d’événement.
Vérifier `x-coussema-signature` avec le secret `signingSecret` renvoyé à la création.
Enregistrer les `message.delivered` et `message.failed` dans votre système métier.
Endpoint recommandé

client.createWebhookEndpoint(...)

import { CoussemaClient } from '@coussema/sdk-js';

const client = new CoussemaClient({
  baseUrl: process.env.COUSSEMA_BASE_URL ?? 'https://api.coussema.com',
  apiKey: process.env.COUSSEMA_API_KEY ?? '',
});

const response = await client.createWebhookEndpoint({
  url: 'https://example.com/webhooks/coussema',
  subscribed_events: ['message.delivered', 'message.failed'],
});

console.log(response.data.signingSecret);
eventmessage.queued
eventmessage.sent
eventmessage.delivered
eventmessage.failed

Headers de callback

La plateforme livre les callbacks avec les headers suivants. Le `x-coussema-delivery-id` vous aide à faire de l’idempotence côté receveur.

content-typeapplication/json
user-agentCoussema-Webhooks/1.0
x-coussema-delivery-iddelivery UUID
x-coussema-eventmessage.delivered
x-coussema-timestamp2026-04-09T10:15:30.000Z
x-coussema-signaturev1=<hmac-sha256-hex>

Payload livré

Le corps du callback contient l’organisation et l’objet message normalisé.

{
  "organization_id": "2f0dd8f4-7b1c-4f38-b4c1-f4bc8aa6e8f4",
  "message": {
    "id": "a2f7e5cb-bbe9-4d7d-bd17-80d1d7a5e5af",
    "campaign_id": null,
    "recipient_phone": "+243810000000",
    "sender_name": "Coussema",
    "status": "delivered",
    "provider_message_id": "provider-msg-123",
    "source_surface": "api",
    "error_code": null,
    "error_message": null,
    "sent_at": "2026-04-09T10:11:11.000Z",
    "failed_at": null,
    "delivered_at": "2026-04-09T10:13:45.000Z"
  }
}

Vérification avec le SDK

Le worker de la plateforme retry les callbacks qui ne retournent pas de 2xx. Vérifiez d’abord la signature, puis dédupliquez et persistez l’événement.

import { assertWebhookSignature, extractCoussemaWebhookHeaders } from '@coussema/sdk-js';

function handleWebhook(rawBody, headers) {
  const webhookHeaders = extractCoussemaWebhookHeaders(headers);

  if (!webhookHeaders.timestamp || !webhookHeaders.signature) {
    throw new Error('Missing Coussema webhook headers.');
  }

  assertWebhookSignature({
    signingSecret: process.env.COUSSEMA_WEBHOOK_SECRET ?? '',
    timestamp: webhookHeaders.timestamp,
    signature: webhookHeaders.signature,
    payload: rawBody,
  });

  return JSON.parse(rawBody);
}
  • Acceptez et dédupliquez par `x-coussema-delivery-id`.
  • Répondez en 2xx une fois le callback enregistré dans votre système.
  • Utilisez le secret retourné à la création pour vérifier la signature.
  • Traitez `message.delivered` et `message.failed` comme les états métier principaux.