Recevoir et vérifier les événements

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-cutuma-event comme la source de vérité pour le type d’événement.
• →Vérifier x-cutuma-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 { CutumaClient } from './cutuma-client.mjs';

const client = new CutumaClient({
  baseUrl: process.env.CUTUMA_BASE_URL ?? 'https://cutuma.com/api/v1',
  apiKey: process.env.CUTUMA_API_KEY ?? '',
});

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

console.log(response.data.signingSecret);

Headers de callback

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

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": "CUTUMA",
    "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,
  extractCutumaWebhookHeaders,
} from './cutuma-client.mjs';

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

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

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

  return JSON.parse(rawBody);
}

• •Acceptez et dédupliquez par x-cutuma-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.