Webhook

Ce document explique comment utiliser le système de webhooks de Yabetoo pour recevoir des notifications en temps réel lorsque des événements se produisent sur votre compte.

Introduction

Les webhooks permettent à votre application de recevoir des notifications en temps réel lorsque des événements se produisent sur votre compte Yabetoo. Au lieu de devoir interroger régulièrement l'API pour vérifier si de nouveaux événements se sont produits, vous pouvez configurer des webhooks pour recevoir des notifications automatiquement.

Types d'événements

Actuellement, le système prend en charge les types d'événements suivants :

intent.completed : Déclenché lorsqu'un paiement est reçu sur votre compte

disbursement.completed : Déclenché lorsqu'un déboursement est effectué depuis votre compte

Créer un Webhook

1. Accéder à l'espace développeur

• Connectez-vous à votre tableau de bord.

• Dans le menu latéral, cliquez sur Développeurs.

1. Ouvrir l’onglet Webhooks

• Une fois sur la page développeur, sélectionnez l’onglet Webhooks en haut (à côté de "Clés API").

1. Ajouter un endpoint

• Cliquez sur le bouton ➕ Ajouter un endpoint en haut à droite.

1. Configurer le webhook

• Renseignez l’URL de votre endpoint (exemple : https://votre-domaine.com/webhook/yabetoo)

• Sélectionnez le type de webhook

• Cliquez sur Enregistrer

Bonnes pratiques

Vérifiez que votre serveur accepte les requêtes POST et répond avec un code 200 OK

Stockez et vérifiez la signature des webhooks fournie (pour plus de sécurité).

En-têtes de sécurité

Chaque requête webhook inclut les en-têtes suivants

X-Yabetoo-Webhook-Signature : Une signature permettant de vérifier l'authenticité de la requête

X-Yabetoo-Webhook-Timestamp : Le timestamp Unix de la requête

X-Yabetoo-Webhook-Event : Le type d'événement (par exemple, intent.completed)

X-Yabetoo-Webhook-Id : L'identifiant unique de la livraison du webhook

Vérification de la signature

Pour vérifier l'authenticité des webhooks reçus, vous devez vérifier la signature incluse dans l'en-tête X-Yabetoo-Webhook-Signature. Voici comment procéder :

1. Récupérez le secret du webhook depuis votre tableau de bord Yabetoo

2. Extrayez le timestamp et la signature de l'en-tête

3. Concaténez le timestamp et le corps de la requête avec un point (.)

4. Calculez une signature HMAC-SHA256 de cette chaîne en utilisant votre secret

5. Comparez cette signature avec celle reçue dans l'en-tête

Exemple de fonction de vérification

JS

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, timestamp, secret) {
  // Concaténer le timestamp et le payload
  const signedPayload = `${timestamp}.${JSON.stringify(payload)}`;
  
  // Calculer la signature HMAC-SHA256
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  // Comparer les signatures (utiliser une comparaison à temps constant)
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

PHP

function verifyWebhookSignature(array $payload, string $signature, string $timestamp, string $secret): bool
{
    // Concaténer le timestamp et le payload encodé en JSON
    $signedPayload = $timestamp . '.' . json_encode($payload, JSON_UNESCAPED_SLASHES);

    // Calculer la signature attendue en HMAC-SHA256
    $expectedSignature = hash_hmac('sha256', $signedPayload, $secret);

    // Comparaison sécurisée en temps constant
    return hash_equals($expectedSignature, $signature);
}

Bonnes pratiques

Répondez rapidement : Votre endpoint doit répondre avec un code 2xx dans les 10 secondes pour éviter les timeouts.

Idempotence : Traitez les webhooks de manière idempotente, car le même événement peut être envoyé plusieurs fois en cas d'échec.

Vérifiez la signature : Vérifiez toujours la signature pour vous assurer que les webhooks proviennent bien de Yabetoo.

Gérez les erreurs : Implémentez une gestion robuste des erreurs pour traiter les échecs de livraison.