Inbound extension webhooks
An extension can receive events from a provider, ERP, store, or other external system through the unique endpoint of its configuration.
Positionnement
Inbound to Ormuz, not outbound webhook
The inbound webhook is called by the connected external system. It lets the extension verify the signal, adapt it to its contract, and expose an extension.*
event usable as a process trigger.
To receive business events that Ormuz sends to your application, see webhooks sortants Ormuz.
Configuration
An endpoint carried by the extension config
When an extension declares the inbound event_in, son
extension_config channel, each configuration automatically exposes an
inbound_endpoint.urlendpoint. There is no separate inbound-webhook object to create, update, or delete.
Only an active configuration accepts events. An extension whose activation depends on a connection test becomes active after that test succeeds.
URL externe
Use the returned public URL
The API returns the complete URL in inbound_endpoint.url. The client must not reconstruct it from its own API-server configuration.
https://api.ormuz.io/v1/extension-webhooks/stripe/pwh_8f4c2d9a1b7e6c3d5a0f
The key identifies the extension definition, for example stripe. The token identifies its configuration for your merchant.
Security
Validation specific to each extension
The mechanism depends on the external system. Stripe, for example, requires the
Stripe-Signature header and
webhook_signing_secret secret configured on the extension.
An inbound webhook does not directly create your business objects. The extension may produce a draft; an explicit process then chooses whether to submit it.
Journal
Received external events
Each receipt produces an extension_inbound_evententry. Its contract uses the generic fields external_event_id and
external_event_type, regardless of extension kind.
| Status | Signification |
|---|---|
received | The signal is accepted and logged, without an Ormuz event. |
ignored | The signal is valid but matches no supported event. |
pending_resolution | A declared business object still needs to be resolved before emission. |
processed | The extension event was emitted with its available inputs. |
resolution_failed | A required business object remains unresolved: no event is emitted. |
failed | Validation, signature verification, or adaptation failed. |
Deduplication uses the external identifier within the extension-config scope. When the source provides none, Ormuz derives a stable fingerprint from the payload.
Orchestration
Extension events
An extension may adapt the signal into a namespaced event, for example
extension.stripe.payment_intent.succeeded. The payload may expose typed external objects, platform-object drafts, and the generic
extension_event.
context. When a required platform output cannot be resolved immediately, Ormuz retries resolution briefly before emission. An optional output may be omitted; an unresolved required output places the log in resolution_failed without emitting the event.
API
Endpoints publics
| Method | Endpoint | Usage |
|---|---|---|
| GET | /v1/extension-configs/{id} | Read the configuration and its inbound endpoint. |
| GET | /v1/extension-configs/{id}/inbound-events | List received external events. |
| POST | /v1/extension-webhooks/{extension_key}/{endpoint_token} | Public URL called by the external system. |