Aperçu des webhooks
Les webhooks permettent à MeSomb de notifier votre application lorsqu’un événement important se produit dans votre compte.
Au lieu d’appeler à plusieurs reprises l’API MeSomb pour vérifier si un paiement a changé, votre application peut exposer un point de terminaison webhook. MeSomb enverra une requête HTTP à ce point de terminaison chaque fois qu’un événement souscrit se produit.
Les cas d’utilisation typiques d’un webhook incluent :
- confirmer qu'une transaction de paiement a réussi ;
- mise à jour d’une commande après la finalisation d’une session de paiement ;
- libération de biens ou de services après qu’un paiement sécurisé a été financé ;
- synchronisation du statut de paiement avec votre système interne ;
- recevoir des notifications de litige, de remboursement, de versement ou de cycle de vie du compte.
Comment fonctionnent les webhooks
Un webhook est une requête HTTP de type POST envoyée par MeSomb à une URL que vous configurez.
Flux d’exemple :
URL d’exemple du point de terminaison webhook :
<span><span style="color: undefined">https://example.com/webhooks/mesomb</span></span>
<span><span style="color: undefined"></span></span>
Votre point de terminaison doit être accessible publiquement via HTTPS.
Structure de l’événement webhook
Tous les événements webhook MeSomb utilisent la même structure de haut niveau.
<span><span style="color: var(--shiki-color-text)">{</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"id"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">"adbbf6bd-1746-4545-a3ce-8b153a7a31b2"</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"object_type"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">"payment"</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"event_type"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">"payment.succeeded"</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"api_version"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">"2026-05-01"</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"created_at"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">"2026-05-07T22:15:30Z"</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"livemode"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">true</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"data"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"object"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"id"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">"txn_01HX9K7A1R6F8MZK2Q9V7N4P5B"</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"object"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">"payment_transaction"</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"status"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">"succeeded"</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"amount"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">15000</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"currency"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">"XAF"</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"reference"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">"ORDER-10045"</span></span>
<span><span style="color: var(--shiki-color-text)"> }</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"previous_attributes"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"status"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">"pending"</span></span>
<span><span style="color: var(--shiki-color-text)"> }</span></span>
<span><span style="color: var(--shiki-color-text)"> }</span></span>
<span><span style="color: var(--shiki-color-text)">}</span></span>
<span></span>
Champs de niveau supérieur
| Champ | Type | Description |
id | string | Identifiant unique de l’événement webhook. Utilisez-le pour la déduplication. |
object_type | string | Toujours event. |
event_type | string | Nom de l’événement, par exemple payment.success. |
api_version | string | Version de l’API MeSomb utilisée pour cette charge utile d’événement. |
created_at | string | Date et heure de création de l’événement, au format UTC ISO 8601. |
livemode | boolean | true pour les événements de production, false pour les événements de test. |
data.object | object | Capture de la ressource affectée par l’événement. |
data.previous_attributes | object | Valeurs précédentes des champs modifiés, lorsqu’elles sont disponibles. |
Convention de nommage des événements
Les noms d’événements MeSomb suivent ce format :
<span><span style="color: undefined">domain.resource.action</span></span>
<span><span style="color: undefined"></span></span>
Exemples :
<span><span style="color: undefined">payment.transaction.succeeded</span></span>
<span><span style="color: undefined">checkout.session.completed</span></span>
<span><span style="color: undefined">secure_payment.transaction.released</span></span>
<span><span style="color: undefined">dispute.created</span></span>
<span><span style="color: undefined">payout.paid</span></span>
<span><span style="color: undefined"></span></span>
Le nom de l’événement doit être utilisé par votre application pour déterminer comment traiter le webhook.
Exemple :
<span><span style="color: var(--shiki-token-keyword)">if</span><span style="color: var(--shiki-color-text)"> event</span><span style="color: var(--shiki-token-punctuation)">[</span><span style="color: var(--shiki-token-string-expression)">"type"</span><span style="color: var(--shiki-token-punctuation)">]</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">==</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">"payment.transaction.succeeded"</span><span style="color: var(--shiki-token-punctuation)">:</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-function)">handle_successful_payment</span><span style="color: var(--shiki-token-punctuation)">(event[</span><span style="color: var(--shiki-token-string-expression)">"data"</span><span style="color: var(--shiki-token-punctuation)">][</span><span style="color: var(--shiki-token-string-expression)">"object"</span><span style="color: var(--shiki-token-punctuation)">])</span></span>
<span><span style="color: var(--shiki-token-keyword)">elif</span><span style="color: var(--shiki-color-text)"> event</span><span style="color: var(--shiki-token-punctuation)">[</span><span style="color: var(--shiki-token-string-expression)">"type"</span><span style="color: var(--shiki-token-punctuation)">]</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">==</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">"checkout.session.completed"</span><span style="color: var(--shiki-token-punctuation)">:</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-function)">handle_completed_checkout</span><span style="color: var(--shiki-token-punctuation)">(event[</span><span style="color: var(--shiki-token-string-expression)">"data"</span><span style="color: var(--shiki-token-punctuation)">][</span><span style="color: var(--shiki-token-string-expression)">"object"</span><span style="color: var(--shiki-token-punctuation)">])</span></span>
<span></span>
Exigences de réponse du webhook
Votre point de terminaison webhook doit renvoyer un code de statut HTTP 2xx lorsque l’événement a été reçu avec succès.
Réponses recommandées :
<span><span style="color: undefined">HTTP/1.1 200 OK</span></span>
<span><span style="color: undefined"></span></span>
ou :
<span><span style="color: undefined">HTTP/1.1 204 No Content</span></span>
<span><span style="color: undefined"></span></span>
Les réponses HTTP 408, HTTP 429, HTTP 5xx et les erreurs réseau temporaires entraînent une nouvelle tentative. Les autres réponses HTTP 4xx terminent la livraison de cet événement sans relance automatique. Les redirections sont refusées : configurez directement l’URL HTTPS finale.
Comportement de réessai
Chaque événement dispose de 6 tentatives automatiques au maximum : la tentative initiale et 5 relances. Les délais sont de 30, 60, 120, 240 et 480 secondes, auxquels s’ajoute à chaque fois un délai aléatoire allant jusqu’à 10 secondes. Ces délais de planification ne constituent pas une garantie de livraison à une heure précise.
Consultez le guide de livraison et de reprise pour connaître les limites de relance, les règles de désactivation automatique et la procédure de réactivation.
Événements en double et idempotence
Les événements webhook peuvent être livrés plus d’une fois.
Utilisez toujours l’ID de l’événement pour détecter les événements en double :
<span><span style="color: var(--shiki-color-text)">{</span></span>
<span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">"id"</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">"adbbf6bd-1746-4545-a3ce-8b153a7a31b2"</span></span>
<span><span style="color: var(--shiki-color-text)">}</span></span>
<span></span>
Comportement recommandé :
- Recevoir le webhook.
- Vérifier la signature.
- Vérifiez si l’ID de l’événement a déjà été traité.
- Si l’événement a déjà été traité, renvoyez
200 OKsans exécuter à nouveau l’action métier. - Si ce n’est pas traité, traitez l’événement et stockez l’ID de l’événement.
Vérification de la signature du webhook
Chaque requête webhook envoyée par MeSomb est signée.
Votre serveur doit vérifier l’en-tête X-MeSomb-Webhook-Signature avant de traiter l’événement.
La vérification de la signature du webhook protège votre intégration contre les requêtes webhook falsifiées ou modifiées.
Consultez le guide complet : Verifying webhook signatures.
Recommandations de sécurité
Avant d’utiliser les webhooks en production :
- utilisez HTTPS pour votre point de terminaison webhook ;
- vérifiez l’en-tête
X-MeSomb-Webhook-Signature; - utilisez le corps brut de la requête pour la vérification de la signature ;
- rejeter les horodatages anciens ;
- stocker les identifiants d’événements traités pour la déduplication ;
- n’exposez pas les secrets de webhook dans le code frontend ou mobile ;
- renvoyez
2xxuniquement lorsque l’événement a été reçu avec succès.
Exemple de flux du gestionnaire de webhook
Modèle de traitement recommandé
Les endpoints Webhook doivent répondre rapidement.
Pour les systèmes de production, évitez d’exécuter une logique métier lourde directement dans la requête HTTP du webhook.
Approche recommandée :
- Vérifier la signature.
- Enregistrez l’événement.
- Renvoyez une réponse
2xx. - Traitez l’événement de manière asynchrone à l’aide d’un worker en arrière-plan.
Cela réduit les risques de dépassement de délai et améliore la fiabilité de la livraison des webhooks.
