Webhooks -- Vue d'ensemble

Les webhooks permettent a votre application de recevoir des notifications en temps reel concernant les evenements de la plateforme Owem Pay. Lorsqu'un evenement se produit, Owem Pay envoie un HTTP POST a l'URL enregistree.

Fonctionnement

1. Enregistrez une URL de webhook sur votre compte
2. Lorsqu'un evenement se produit (ex : PIX recu), Owem Pay envoie un HTTP POST a votre URL
3. Votre application traite la notification et repond avec le statut 2xx (200, 201 ou 204)

Evenements Disponibles

Evenement	Description
pix.received	PIX recu sur le compte (cash-in confirme)
pix.completed	Virement PIX envoye avec succes (cash-out)
pix.failed	Virement PIX echoue
pix.refund	Remboursement PIX traite
pix.med	Notification MED recue du BACEN

Securite

Chaque notification inclut des en-tetes de securite pour validation :

En-tete	Description
X-Owem-Signature	Signature HMAC-SHA256 du payload
X-Owem-Timestamp	Horodatage de l'envoi (ISO 8601)
X-Owem-Event-Id	ID unique de l'evenement (pour deduplication)
X-Owem-Event-Type	Type de l'evenement (ex : pix.received)

Validation de la Signature

Validez la signature pour vous assurer que la notification a ete envoyee par Owem Pay :

const crypto = require('crypto');

function validateWebhook(payload, timestamp, signature, secret) {
  const message = `${timestamp}.${payload}`;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Validez toujours

Ne traitez jamais un webhook sans valider la signature. Cela protege contre les requetes falsifiees.

Politique de Nouvelles Tentatives

Si votre URL retourne un statut different de 2xx, Owem Pay effectue des nouvelles tentatives automatiques :

Tentative	Intervalle
1re	Immediat
2e	1 minute
3e	5 minutes
4e	30 minutes
5e	2 heures

Apres 5 tentatives sans succes, l'evenement est marque comme failed et ne sera pas renvoye automatiquement.

Idempotence

Votre application doit etre idempotente : si elle recoit le meme evenement plus d'une fois (identifie par le X-Owem-Event-Id), elle doit le traiter sans dupliquer les effets.

Exigences de l'Endpoint

• L'URL doit utiliser HTTPS
• Doit repondre avec le statut 2xx dans un delai de 5 secondes
• Le body de la reponse est ignore

Etapes Suivantes

• Enregistrer un Webhook -- creer, lister et supprimer des webhooks
• Payloads des Evenements -- exemples de chaque type d'evenement