Configuration des Webhooks

Les webhooks permettent à Sangho de notifier votre serveur en temps réel lorsque des événements se produisent sur votre compte. Vous pouvez créer et gérer vos endpoints depuis le dashboard ou via l’API Webhooks.

Créer un endpoint depuis le dashboard

1. Accédez à Dashboard → Développeurs → Webhooks.
2. Cliquez sur Ajouter un endpoint.
3. Saisissez l'URL HTTPS de votre serveur.
4. Sélectionnez les événements à écouter (ou Tous les événements).
5. Cliquez sur Créer — copiez le webhook_secret affiché une seule fois.

Exigences de l’endpoint

URL HTTPS valide (HTTP refusé sauf localhost en Sandbox).
Réponse HTTP 200 dans les 30 secondes.
Corps de la réponse ignoré — seul le code HTTP compte.
Endpoint accessible publiquement depuis internet.

Répondez 200 immédiatement

Répondez toujours HTTP 200 immédiatement, même si le traitement métier échoue. Gérez les erreurs en arrière-plan pour éviter les relivraisons inutiles. Consultez le guide Idempotence pour la gestion des doublons.

La configuration est-elle claire ?

Endpoint minimal (Express)

javascript

const express = require('express');
const app = express();


// IMPORTANT : utiliser express.raw, pas express.json
app.post(
  '/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const event = JSON.parse(req.body);
    console.log('Événement reçu :', event.type);


    // Traiter en arrière-plan, répondre immédiatement
    processEvent(event).catch(console.error);


    res.status(200).json({ received: true });
  },
);

Politique de retry

Si votre endpoint ne répond pas 200 dans les 30 secondes, Sangho retente la livraison 10 fois selon un délai exponentiel.

Tentative	Délai cumulé
1	Immédiat
2	+5 min
3	+15 min
4	+30 min
5	+1 h
6	+2 h
7	+4 h
8	+8 h
9	+16 h
10	+24 h puis +48 h

Tester un endpoint

Depuis la fiche d’un endpoint dans le dashboard, cliquez sur Envoyer un événement test. Sélectionnez le type d’événement et Sangho envoie un payload réel à votre endpoint. Vous pouvez également utiliser l’API :

Tunnel local pour les tests

Pour tester votre endpoint en développement local, utilisez ngrok ou localtunnel pour exposer votre serveur local via une URL HTTPS publique.

La politique de retry est-elle bien expliquée ?

Envoyer un événement test (API)

bash

curl -X POST https://api.sangho.com/v1/webhooks/wh_xxx/test/ \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "event_type": "payment_intent.succeeded" }'

Response 200 OK — Événement test envoyé

Sangho envoie un payload réel à votre endpoint. Vérifiez vos logs de livraison pour confirmer la réception.

json

{
  "id": "evt_test_xxxxxxxxxxxx",
  "object": "event",
  "type": "payment_intent.succeeded",
  "livemode": false,
  "test": true,
  "created_at": "2026-03-01T10:00:00Z"
}