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.charge.created	QR Code genere (cash-in en attente)
pix.charge.paid	PIX recu sur le compte (cash-in confirme)
pix.charge.expired	QR Code expire sans paiement
pix.payout.created	Virement PIX cree (cash-out)
pix.payout.confirmed	Virement PIX envoye avec succes
pix.payout.failed	Virement PIX echoue
pix.payout.returned	Virement PIX retourne par le destinataire
pix.refund.requested	Demande de remboursement MED recue du BACEN
pix.refund.completed	Remboursement MED traite
pix.return.received	Remboursement PIX recu
webhook.test	Evenement de test pour valider l'URL

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.charge.paid)

SHA256 pour les webhooks vs SHA512 pour l'API

L'API utilise HMAC-SHA512 pour authentifier les requetes que vous envoyez. Les webhooks envoyes par Owem Pay utilisent HMAC-SHA256 dans la signature X-Owem-Signature. Ce sont des algorithmes differents -- chacun dans son contexte.

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.

External ID dans les Webhooks

Lorsqu'une transaction a ete creee avec external_id, ce champ est inclus dans le payload du webhook au sein de l'objet data. Utilisez-le pour correler l'evenement avec la commande dans votre systeme sans avoir besoin d'effectuer une requete supplementaire.

Exigences de l'Endpoint

• L'URL doit utiliser HTTPS (sauf si allow_insecure: true lors de l'enregistrement)
• Doit repondre avec le statut 2xx dans un delai de 5 secondes
• Le body de la reponse est ignore

Prochaines Etapes

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