Webhooks

Les webhooks vous permettent de recevoir des notifications en temps réel lorsque le statut d'une transaction change. Configurez un endpoint sur votre serveur pour traiter ces événements automatiquement.

Comment ça fonctionne

Transaction initiée

Vous lancez une collecte via l'API. Le client reçoit une demande de validation sur son téléphone.

Signature HMAC

Quand le statut change, SebPay envoie un POST à votre callback_url avec une signature HMAC-SHA256 dans l'en-tête.

Confirmation

Votre serveur vérifie la signature et met à jour la commande en conséquence.

Payload du webhook

Lorsqu'une transaction atteint un statut final (approved ou rejected), SebPay envoie un POST JSON à l'URL de callback que vous avez spécifiée.

POST

{your_callback_url}

Votre endpoint doit répondre avec un code HTTP 200 pour confirmer la réception.

Headers

X-SebPay-SignatureRequired

string

Signature HMAC-SHA256 du body JSON, calculée avec votre clé secrète (sk_...).

Content-TypeRequired

string

application/json

Request Body

transaction_idRequired

string

Identifiant unique de la transaction SebPay.

external_referenceRequired

string

Votre référence externe fournie lors de la création.

statusRequired

string

Statut final : approved, rejected ou pending.

amountRequired

numeric

Montant de la transaction.

currencyRequired

string

Code de la devise (XOF, EUR, etc.).

customer_phoneRequired

string

Numéro de téléphone du client.

created_atRequired

datetime

Date de création de la transaction.

updated_atRequired

datetime

Date de dernière mise à jour.

Valeurs possibles du statut

approvedLe paiement a été confirmé avec succès par le client.

rejectedLe paiement a échoué, a été annulé ou a expiré.

pendingLe paiement est en attente de validation par le client.

Vérification de la signature

Pour garantir l'authenticité du webhook, vous devez vérifier la signature HMAC-SHA256 envoyée dans l'en-tête X-SebPay-Signature. Utilisez votre clé secrète pour recalculer la signature et la comparer.

# Test your own webhook endpoint locally with curl
# Replace https://yoursite.com/webhook/sebpay with your actual callback URL
curl -X POST https://yoursite.com/webhook/sebpay \
  -H "Content-Type: application/json" \
  -H "X-SebPay-Signature: your_computed_hmac_here" \
  -d '{
    "transaction_id": "20260505120000123456",
    "external_reference": "ORDER-789",
    "status": "approved",
    "amount": 5000,
    "currency": "XOF",
    "customer_phone": "22997000000",
    "created_at": "2026-05-05T12:00:00.000000Z",
    "updated_at": "2026-05-05T12:01:30.000000Z"
  }'

Bonnes pratiques

Toujours vérifier la signature

Ne traitez jamais un webhook sans avoir vérifié la signature HMAC. Cela protège votre application contre les requêtes frauduleuses.

Répondre rapidement (HTTP 200)

Votre endpoint doit répondre avec un HTTP 200 dans les 5 secondes. Si le traitement est long, enregistrez l'événement et traitez-le de manière asynchrone.

Gérer l'idempotence

Un même webhook peut être envoyé plusieurs fois en cas de retry. Utilisez le transaction_id pour éviter de traiter deux fois le même événement.