Receive webhooks
Ormuz webhooks deliver platform business events to your systems with a stable JSON payload and a Svix signature that must be verified before processing.
Model
Endpoint webhook
A webhook endpoint belongs to a merchant and targets an HTTPS URL in your application. It receives the events listed in filter_types. When no filter is defined, the endpoint receives events compatible with its configuration.
Event types delivered to this endpoint, for example invoice.issued.
Signing secret managed by Svix for this endpoint. Retrieve it with
GET /v1/webhooks/{endpoint_id}/secret and store it on the receiving side.
A disabled endpoint receives no more deliveries.
Attempts, HTTP responses, retries, and replays are available through webhook-observability endpoints.
Configuration
Create and manage an endpoint
Create an endpoint with your handler's public URL and the list of events to receive. Then retrieve the endpoint signing secret and store it in your receiving system.
| Method | Endpoint | Usage |
|---|---|---|
| POST | /v1/webhooks | Create a webhook endpoint for a merchant. |
| GET | /v1/webhooks?merchant_id=mer_... | List a merchant's endpoints. |
| POST | /v1/webhooks/{endpoint_id} | Update the URL, subscribed events, channels, or status. |
| DELETE | /v1/webhooks/{endpoint_id} | Supprimer l’endpoint. |
| GET | /v1/webhooks/{endpoint_id}/secret?merchant_id=mer_... | Retrieve the endpoint's Svix signing secret. |
| POST | /v1/webhooks/{endpoint_id}/secret/rotate | Rotate the Svix signing secret. |
| POST | /v1/webhooks/test | Trigger a test delivery within a merchant scope. |
| GET | /v1/webhooks/{endpoint_id}/attempts?merchant_id=mer_... | List delivery attempts. |
Delivery
Delivered event format
Ormuz sends a POST JSON request. The body contains the event identifier, type, merchant, timestamp, and relevant business payload.
Respond with an HTTP 2xx status only after persisting or deduplicating the event in the receiving system. Use id as the idempotency key.
Headers
| Header | Description |
|---|---|
svix-id | Unique identifier of the signed message. It is part of signature calculation. |
svix-timestamp | Signed Unix timestamp. Reject timestamps outside tolerance to limit replays. |
svix-signature | Versioned Svix signature containing one or more v1. |
Security
Verify the signature
Verify the signature against the raw received body before parsing JSON. Ormuz outbound webhooks use Svix signatures; legacy X-Webhook-Signature headers are no longer emitted. Prefer a Svix library with the secret returned for the endpoint: it applies the versioned signature format and timestamp verification without reimplementing the protocol.
- Preserve the raw body and read
svix-id,svix-timestampandsvix-signature. - Verify the message with the endpoint secret and a Svix library.
- Reject delivery when the signature or its time window is invalid.
- After verification, deduplicate processing using the event identifier.
Abonnements
Choose events
The filter_types field accepts only Core platform events declared deliverable by webhook. The extension.* events are used for internal orchestration and are not outbound-webhook subscription types. Prefer an explicit list when your endpoint needs only a subset of events.
| Family | Examples |
|---|---|
| Company | company.created, company.updated, contact.created, contact_role.certified |
| Onboarding & compliance | onboarding_case.completed, onboarding_case.rejected, compliance_check.created, compliance_check.review_required |
| Commerce | order.created, order.confirmed, checkout_session.completed |
| Invoicing | invoice.created, invoice.issued, invoice.sent, invoice.cancelled |
| Payments | psp_payment.succeeded, payment.received, payment_allocation.complete |
| Orchestration | process.instance.replayed, process.user_action.completed, approval_request.resolved |
For the complete list and type semantics, see the event catalog.
Operations
Test and operate
Use POST /v1/webhooks/test to trigger a test delivery for the merchant. The received delivery has type webhook.test.
- Temporarily disable an endpoint with
disabledwhen you need to pause deliveries. - Inspect attempts to see HTTP statuses, errors, timestamps, and observed responses.
- Use message replay when your endpoint failed after a receiver-side incident.