Recevoir des webhooks

Les webhooks Ormuz livrent les événements métier de la plateforme à vos systèmes, avec un payload JSON stable et une signature Svix à vérifier avant traitement.

Modèle

Endpoint webhook

Un endpoint webhook appartient à un marchand et cible une URL HTTPS de votre application. Il reçoit les événements listés dans filter_types. Si aucun filtre n’est défini, l’endpoint reçoit les événements compatibles avec sa configuration.

filter_typesstring[] | null

Types d’événements livrés à cet endpoint, par exemple invoice.issued.

secretstring

Secret de signature géré par Svix pour cet endpoint. Récupérez-le avec GET /v1/webhooks/{endpoint_id}/secret et stockez-le côté receveur.

disabledboolean

Un endpoint désactivé ne reçoit plus de livraisons.

attemptslist

Les tentatives, réponses HTTP, retries et rejeux sont consultables via les endpoints d’observabilité webhook.

Configuration

Créer et gérer un endpoint

Créez un endpoint avec l’URL publique de votre handler et la liste des événements à recevoir. Récupérez ensuite le secret de signature de l’endpoint, puis stockez-le dans votre système receveur.

Méthode	Endpoint	Usage
POST	`/v1/webhooks`	Créer un endpoint webhook pour un marchand.
GET	`/v1/webhooks?merchant_id=mer_...`	Lister les endpoints d’un marchand.
POST	`/v1/webhooks/{endpoint_id}`	Mettre à jour l’URL, les événements abonnés, les channels ou le statut.
DELETE	`/v1/webhooks/{endpoint_id}`	Supprimer l’endpoint.
GET	`/v1/webhooks/{endpoint_id}/secret?merchant_id=mer_...`	Récupérer le secret de signature Svix de l’endpoint.
POST	`/v1/webhooks/{endpoint_id}/secret/rotate`	Faire tourner le secret de signature Svix.
POST	`/v1/webhooks/test`	Déclencher une livraison de test dans le périmètre d’un marchand.
GET	`/v1/webhooks/{endpoint_id}/attempts?merchant_id=mer_...`	Lister les tentatives de livraison.

Livraison

Format des événements livrés

Ormuz envoie une requête POST en JSON. Le corps contient l’identifiant de l’événement, son type, le marchand, l’horodatage et le payload métier concerné.

Répondez avec un statut HTTP 2xx seulement après avoir persisté ou dédupliqué l’événement côté système receveur. Utilisez id comme clé d’idempotence.

Headers

Header	Description
`svix-id`	Identifiant unique du message signé. Il entre dans le calcul de signature.
`svix-timestamp`	Timestamp Unix signé. Refusez les timestamps hors tolérance pour limiter les replays.
`svix-signature`	Signature Svix versionnée, contenant une ou plusieurs valeurs `v1`.

Sécurité

Vérifier la signature

Vérifiez la signature sur le corps brut reçu, avant parsing JSON. Les webhooks sortants Ormuz utilisent les signatures Svix ; les anciens headers X-Webhook-Signature ne sont plus émis. Utilisez de préférence une bibliothèque Svix avec le secret retourné pour l’endpoint : elle applique le format de signature versionné et la vérification temporelle sans réimplémenter le protocole.

Conserver le corps brut et lire svix-id, svix-timestamp et svix-signature.
Vérifier le message avec le secret de l’endpoint et une bibliothèque Svix.
Refuser la livraison si la signature ou sa fenêtre temporelle n’est pas valide.
Après vérification, dédupliquer le traitement avec l’identifiant de l’événement.

Abonnements

Choisir les événements

Le champ filter_types accepte uniquement les événements plateforme Core déclarés comme livrables par webhook. Les événements extension.* servent à l’orchestration interne et ne sont pas des types d’abonnement de webhook sortant. Préférez une liste explicite lorsque votre endpoint n’a besoin que d’un sous-ensemble d’événements.

Famille	Exemples
Entreprise	`company.created, company.updated, contact.created, contact_role.certified`
Onboarding & conformité	`onboarding_case.completed, onboarding_case.rejected, compliance_check.created, compliance_check.review_required`
Commerce	`order.created, order.confirmed, checkout_session.completed`
Facturation	`invoice.created, invoice.issued, invoice.sent, invoice.cancelled`
Paiements	`psp_payment.succeeded, payment.received, payment_allocation.complete`
Orchestration	`process.instance.replayed, process.user_action.completed, approval_request.resolved`

Pour la liste complète et la sémantique des types, consultez le catalogue des événements.

Exploitation

Tester et opérer

Utilisez POST /v1/webhooks/test pour déclencher une livraison de test sur le marchand. La livraison reçue porte le type webhook.test.

Désactivez temporairement un endpoint avec disabled si vous devez suspendre les livraisons.
Consultez les tentatives pour voir les statuts HTTP, erreurs, timestamps et réponses observées.
Utilisez le replay de message lorsque votre endpoint a échoué après un incident côté receveur.