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 :

flowchart TD A[Customer completes payment] --> B[MeSomb creates an event] B --> C[MeSomb sends a webhook to your endpoint] C --> D[Your server verifies the signature] D --> E[Your server processes the event] E --> F[Your server returns a 2xx response]

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)">&quot;id&quot;</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)">&quot;adbbf6bd-1746-4545-a3ce-8b153a7a31b2&quot;</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)">&quot;object_type&quot;</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)">&quot;payment&quot;</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)">&quot;event_type&quot;</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)">&quot;payment.succeeded&quot;</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)">&quot;api_version&quot;</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)">&quot;2026-05-01&quot;</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)">&quot;created_at&quot;</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)">&quot;2026-05-07T22:15:30Z&quot;</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)">&quot;livemode&quot;</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)">&quot;data&quot;</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)">&quot;object&quot;</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)">&quot;id&quot;</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)">&quot;txn_01HX9K7A1R6F8MZK2Q9V7N4P5B&quot;</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)">&quot;object&quot;</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)">&quot;payment_transaction&quot;</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)">&quot;status&quot;</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)">&quot;succeeded&quot;</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)">&quot;amount&quot;</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)">&quot;currency&quot;</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)">&quot;XAF&quot;</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)">&quot;reference&quot;</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)">&quot;ORDER-10045&quot;</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)">&quot;previous_attributes&quot;</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)">&quot;status&quot;</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)">&quot;pending&quot;</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

ChampTypeDescription
idstringIdentifiant unique de l’événement webhook. Utilisez-le pour la déduplication.
object_typestringToujours event.
event_typestringNom de l’événement, par exemple payment.success.
api_versionstringVersion de l’API MeSomb utilisée pour cette charge utile d’événement.
created_atstringDate et heure de création de l’événement, au format UTC ISO 8601.
livemodebooleantrue pour les événements de production, false pour les événements de test.
data.objectobjectCapture de la ressource affectée par l’événement.
data.previous_attributesobjectValeurs 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)">&quot;type&quot;</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)">&quot;payment.transaction.succeeded&quot;</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)">&quot;data&quot;</span><span style="color: var(--shiki-token-punctuation)">][</span><span style="color: var(--shiki-token-string-expression)">&quot;object&quot;</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)">&quot;type&quot;</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)">&quot;checkout.session.completed&quot;</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)">&quot;data&quot;</span><span style="color: var(--shiki-token-punctuation)">][</span><span style="color: var(--shiki-token-string-expression)">&quot;object&quot;</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.

Livraison et reprise

É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)">&quot;id&quot;</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)">&quot;adbbf6bd-1746-4545-a3ce-8b153a7a31b2&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">}</span></span>
<span></span>

Comportement recommandé :

  1. Recevoir le webhook.
  2. Vérifier la signature.
  3. Vérifiez si l’ID de l’événement a déjà été traité.
  4. Si l’événement a déjà été traité, renvoyez 200 OK sans exécuter à nouveau l’action métier.
  5. 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 2xx uniquement lorsque l’événement a été reçu avec succès.

Exemple de flux du gestionnaire de webhook

flowchart TD A[Receive POST request] --> B[Read raw request body] B --> C[Verify X-MeSomb-Webhook-Signature] C --> D[Parse JSON event] D --> E[Check event.id for duplicates] E --> F[Process event by type] F --> G[Store processing result] G --> H[Return 200 or 204]

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 :

  1. Vérifier la signature.
  2. Enregistrez l’événement.
  3. Renvoyez une réponse 2xx .
  4. 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.