Être prévenu : webhooks

pismile envoie un message signé à votre serveur quand un paiement est terminé. Événements, signature, nouvelles tentatives.

3 min de lecture · Mis à jour le 25/10/2026 · API v1

Un webhook, c'est pismile qui appelle votre serveur pour le prévenir : « la commande cmd-42 est payée ». Vous n'avez pas à interroger pismile en boucle : l'information vient à vous, en quelques secondes.

Configurer#

Console → Applications → votre application → Paiements → section « Être prévenu (webhook) » :

Indiquez votre adresse
Une adresse HTTPS de votre serveur, par exemple https://votre-site.com/webhooks/pismile. Les adresses de réseaux privés ou locaux sont refusées.
Copiez le secret
Le secret whsec_… s'affiche une seule fois. Mettez-le dans la configuration de votre serveur (PISMILE_WEBHOOK_SECRET). Perdu ? Cliquez sur Générer un nouveau secret (l'ancien cesse aussitôt de fonctionner).
Envoyez un test
Envoyer un test envoie un événement test. Le résultat (code HTTP, erreur éventuelle) s'affiche dans Derniers envois.

Les événements#

Événement	Quand	Que faire
`session.payee`	Une page de paiement est entièrement payée	Livrer, valider la commande
`session.expiree`	La page a expiré (30 min) sans paiement complet	Annuler la commande ; si `montantPaye` > 0, compléter ou rembourser cette partie
`paiement.paye`	Une demande de paiement est payée	Valider la facture
`paiement.refuse` · `paiement.annule` · `paiement.expire`	La demande n'a pas abouti (rien n'est débité)	Relancer l'utilisateur si besoin
`test`	Bouton « Envoyer un test »	Rien

Ce que contient un webhook#

Une requête POST avec un corps JSON :

JSON

{
  "id": "evt_8k2m4q7x9z3c5v1b6n8p2r4t",
  "type": "session.payee",
  "creeLe": "2026-10-25T10:42:07Z",
  "test": false,
  "donnees": {
    "id": "cs_Hq2…",
    "url": "https://pismile.com/payer/cs_Hq2…",
    "reference": "cmd-42",
    "montant": 25000,
    "devise": "XOF",
    "motif": "Ma Boutique - Commande 42",
    "statut": "PAYEE",
    "montantPaye": 25000,
    "creeLe": "2026-10-25T10:38:51Z",
    "expireLe": "2026-10-25T11:08:51Z",
    "payeLe": "2026-10-25T10:42:07Z",
    "test": false
  }
}

Et des en-têtes : Pismile-Evenement (le type), Pismile-Livraison (l'identifiant de l'événement) et Pismile-Signature.

Vérifier la signature (obligatoire)#

La signature prouve que le message vient bien de pismile et n'a pas été modifié. Les SDK le font pour vous (webhooks.verifier) : voir les exemples du bouton. Sans SDK :

Lisez l'en-tête Pismile-Signature: t=1761388927,v1=5257a869e7…
Calculez HMAC-SHA256(secret, t + "." + corps_brut) en hexadécimal.
Comparez avec v1 (comparaison à temps constant), et refusez si t date de plus de 5 minutes.

Répondre#

Répondez 2xx (200, 204…) en moins de 10 secondes. Faites les traitements longs après avoir répondu.
Si pismile ne reçoit pas de 2xx, il réessaie : après 1 min, 5 min, 30 min, 2 h, 6 h, 12 h et 24 h, puis abandonne. Vous pouvez relancer un envoi depuis la console.
Un même événement peut arriver deux fois (réseau, nouvelle tentative). Rendez votre traitement sans effet la deuxième fois : « marquer payée » une commande déjà payée ne doit rien changer. Vous pouvez aussi mémoriser l'id des événements traités.

Exclure le webhook de la protection CSRF#

Le webhook est appelé par le serveur pismile, pas par un navigateur : il n'a ni cookie ni jeton CSRF.

Framework	Réglage
Spring Security	`http.csrf(c -> c.ignoringRequestMatchers("/webhooks/pismile"))`
Laravel	`->withoutMiddleware(VerifyCsrfToken::class)` sur la route
Django	décorateur `@csrf_exempt`
Express	rien à faire (pas de CSRF par défaut)

Sans webhook#

Vous pouvez aussi relire l'état d'une page de paiement quand vous en avez besoin : GET /api/v1/sessions-paiement/{id} (voir la référence de l'API). Pratique en secours, mais le webhook reste la méthode recommandée.

Cette page vous a-t-elle aidé ?