Webhooks

Configuration

Créez un endpoint dans le menu Développeurs, section Webhooks, ou via POST /merchant/merchants/:id/webhook-endpoints.

Le secret whsec_… n'est affiché qu'une fois. Pour faire tourner le secret sans recréer l'URL : POST …/webhook-endpoints/:endpointId/rotate-secret.

Signature

Chaque livraison inclut X-Izzi-Signature (HMAC-SHA256, hex sans préfixe) et X-Izzi-Timestamp (secondes Unix).

Corps signé : concaténation {timestamp}.{rawBody} (point littéral entre les deux).

Fenêtre de validité recommandée : 300 secondes. Vérifiez la signature avant de parser le JSON.

En-tête X-Izzi-Event-Id : identifiant unique de la livraison (idempotence côté récepteur).

import { verifyWebhookSignature } from "@izzipay/sdk";

const result = verifyWebhookSignature({
  secret: process.env.IZZI_WEBHOOK_SECRET!,
  rawBody: requestBody,
  signature: request.headers["x-izzi-signature"],
  timestamp: request.headers["x-izzi-timestamp"],
});

if (!result.verified) {
  throw new Error(result.reason ?? "invalid signature");
}

Relivraison

Jusqu'à 20 tentatives par événement, backoff exponentiel (1 s → 1 h), timeout HTTP 8 s par tentative.

Circuit breaker après échecs répétés sur un endpoint ; consultez l'historique via GET …/webhook-deliveries.

Adresses IP sortantes

IZZIPAY ne publie pas de liste fixe d'IP egress pour les webhooks. Authentifiez chaque requête via la signature HMAC plutôt que par filtrage IP.

Événements

Voir la référence API Webhooks pour les payloads exemples de chaque type.