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.