Webhooks entrants des extensions
Une extension peut recevoir les événements d’un provider, d’un ERP, d’une boutique ou d’un autre système externe grâce à l’endpoint unique de sa configuration.
Positionnement
Entrant vers Ormuz, pas webhook sortant
Le webhook entrant est appelé par le système externe connecté. Il permet à l’extension de vérifier le
signal, de l’adapter à son contrat et d’exposer un événement extension.*
utilisable comme déclencheur de processus.
Pour recevoir les événements métier qu’Ormuz envoie à votre application, consultez plutôt les webhooks sortants Ormuz.
Configuration
Un endpoint porté par l’extension config
Lorsqu’une extension déclare le canal entrant event_in, son
extension_config expose automatiquement un
inbound_endpoint.url. Il n’existe pas d’objet webhook entrant séparé à
créer, mettre à jour ou supprimer.
Seule une configuration active accepte des événements. Une extension dont l’activation dépend d’un test de connexion devient active après la réussite de ce test.
URL externe
Utiliser l’URL publique retournée
L’API retourne l’URL complète dans inbound_endpoint.url. Le client ne
doit pas la reconstruire à partir de sa propre configuration du serveur API.
https://api.ormuz.io/v1/extension-webhooks/stripe/pwh_8f4c2d9a1b7e6c3d5a0f
La clé identifie la définition d’extension, par exemple stripe. Le token
identifie sa configuration pour votre marchand.
Sécurité
Validation propre à chaque extension
Le mécanisme dépend du système externe. Stripe exige par exemple le header
Stripe-Signature et le secret
webhook_signing_secret configuré sur l’extension.
Un webhook entrant ne crée pas directement vos objets métier. L’extension peut produire un draft ; un processus explicite choisit ensuite de le soumettre.
Journal
Événements externes reçus
Chaque réception produit un extension_inbound_event. Son contrat utilise
les champs génériques external_event_id et
external_event_type, quel que soit le kind de l’extension.
| Statut | Signification |
|---|---|
received | Le signal est accepté et journalisé, sans événement Ormuz. |
ignored | Le signal est valide mais ne correspond à aucun événement pris en charge. |
pending_resolution | Un objet métier déclaré doit encore être résolu avant l’émission. |
processed | L’événement d’extension a été émis avec ses entrées disponibles. |
resolution_failed | Un objet métier obligatoire reste introuvable : aucun événement n’est émis. |
failed | La validation, la signature ou l’adaptation a échoué. |
La déduplication utilise l’identifiant externe dans le périmètre de l’extension config. Si la source n’en fournit pas, Ormuz dérive une empreinte stable du payload.
Orchestration
Événements d’extension
Une extension peut adapter le signal en événement namespacé, par exemple
extension.stripe.payment_intent.succeeded. Le payload peut exposer des
objets externes typés, des drafts d’objets plateforme et le contexte générique
extension_event.
Lorsqu’un output plateforme obligatoire n’est pas imm édiatement résolvable, Ormuz retente brièvement sa
résolution avant l’émission. Un output facultatif peut être omis ; un output obligatoire non résolu place
le journal en resolution_failed sans émettre l’événement.
API
Endpoints publics
| Méthode | Endpoint | Usage |
|---|---|---|
| GET | /v1/extension-configs/{id} | Lire la configuration et son endpoint entrant. |
| GET | /v1/extension-configs/{id}/inbound-events | Lister les événements externes reçus. |
| POST | /v1/extension-webhooks/{extension_key}/{endpoint_token} | URL publique appelée par le système externe. |