API Webhooks

Créer, gérer et configurer des webhooks pour recevoir des notifications en temps réel sur les événements email.

Lister les Webhooks

Obtenir tous les webhooks configurés pour votre organisation.

Endpoint


GET /api/webhooks

Exemple de Requête


curl -X GET NEXT_PUBLIC_BASE_URL/api/webhooks \
  -H "x-api-key: votre-cle-api"

Schéma de Réponse

Champ	Type	Description
`id`	`string`	Identifiant unique du webhook
`url`	`string`	URL de destination des payloads
`events`	`string[]`	Liste des événements souscrits
`secret`	`string`	Secret de signature HMAC (32 caractères)
`isActive`	`boolean`	Si le webhook est actif
`organizationId`	`string`	Identifiant de l’organisation
`createdAt`	`string`	Timestamp ISO 8601 de création
`updatedAt`	`string`	Timestamp ISO 8601 de dernière modification

Exemple de Réponse


[
  {
    "id": "wh_abc123",
    "url": "https://example.com/webhooks/mailpulse",
    "events": ["EMAIL_SENT", "EMAIL_OPENED"],
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "isActive": true,
    "organizationId": "org_xyz789",
    "createdAt": "2024-03-10T14:00:00.000Z",
    "updatedAt": "2024-03-10T14:00:00.000Z"
  }
]

Créer un Webhook

Enregistrer un nouveau endpoint webhook pour votre organisation.

Endpoint


POST /api/webhooks

Corps de la Requête

Champ	Type	Requis	Description
`url`	`string`	Oui	URL de destination (HTTPS requis)
`events`	`string[]`	Oui	Événements à souscrire

Événements disponibles : EMAIL_SENT, EMAIL_OPENED, EMAIL_CLICKED.

Exemple de Requête


curl -X POST NEXT_PUBLIC_BASE_URL/api/webhooks \
  -H "x-api-key: votre-cle-api" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/mailpulse",
    "events": ["EMAIL_SENT", "EMAIL_OPENED", "EMAIL_CLICKED"]
  }'

Exemple de Réponse


{
  "id": "wh_abc123",
  "url": "https://example.com/webhooks/mailpulse",
  "events": ["EMAIL_SENT", "EMAIL_OPENED", "EMAIL_CLICKED"],
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "isActive": true,
  "organizationId": "org_xyz789",
  "createdAt": "2024-03-10T14:00:00.000Z",
  "updatedAt": "2024-03-10T14:00:00.000Z"
}

Mettre à Jour un Webhook

Modifier l’URL, les événements ou le statut actif d’un webhook existant.

Endpoint


PATCH /api/webhooks/:id

Paramètres de Chemin

Paramètre	Type	Description
`id`	`string`	ID du Webhook

Corps de la Requête

Champ	Type	Requis	Description
`url`	`string`	Non	Nouvelle URL de destination
`events`	`string[]`	Non	Liste d’événements mise à jour
`isActive`	`boolean`	Non	Activer ou désactiver le webhook

Exemple de Requête


curl -X PATCH NEXT_PUBLIC_BASE_URL/api/webhooks/wh_abc123 \
  -H "x-api-key: votre-cle-api" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["EMAIL_OPENED"],
    "isActive": false
  }'

Exemple de Réponse


{
  "id": "wh_abc123",
  "url": "https://example.com/webhooks/mailpulse",
  "events": ["EMAIL_OPENED"],
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "isActive": false,
  "organizationId": "org_xyz789",
  "createdAt": "2024-03-10T14:00:00.000Z",
  "updatedAt": "2024-03-12T09:15:00.000Z"
}

Supprimer un Webhook

Supprimer un webhook de votre organisation.

Endpoint


DELETE /api/webhooks/:id

Paramètres de Chemin

Paramètre	Type	Description
`id`	`string`	ID du Webhook

Exemple de Requête


curl -X DELETE NEXT_PUBLIC_BASE_URL/api/webhooks/wh_abc123 \
  -H "x-api-key: votre-cle-api"

Exemple de Réponse


{
  "success": true
}

Vérification de Signature

Chaque requête webhook inclut une signature HMAC-SHA256 dans l’en-tête x-webhook-signature. Utilisez le secret de votre objet webhook pour vérifier l’authenticité du payload.

Exemple de Vérification (Node.js)


import crypto from "crypto";
 
function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(payload))
    .digest("hex");
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Réponses d’Erreur

Statut	Description
`401 Unauthorized`	Clé API invalide ou manquante
`404 Not Found`	Webhook non trouvé ou n’appartenant pas à votre organisation

Exemple d’Erreur


{
  "error": "Unauthorized"
}