Webhooks

🔗 Webhooks

OrderEazi Central can notify your systems in real time when events occur - such as orders being dispatched, documents being created, or stock levels changing. It does this by sending HTTP POST requests with JSON payloads to URLs you configure.

🧾 What are Webhooks?

A webhook is an HTTP callback. When something happens in OrderEazi, the system serialises the event data as JSON and delivers it to your endpoint.

You choose which events to listen to and where to send them. OrderEazi handles queuing, delivery, and retries.

⚙️ How Webhooks Work

When an event occurs in OrderEazi Central:

• The event data is serialised to a JSON payload

• A queue entry is created for each registered webhook matching that event

• A background processor dispatches all pending webhooks every minute

• Your endpoint receives an HTTP POST with the JSON payload

• If delivery fails, OrderEazi retries up to 3 times before marking the webhook as failed

🚀 Quick Start

To start receiving webhooks:

1. Obtain an API key from your OrderEazi administrator (you need Write_Administrative_Data permission)

2. Register a webhook by calling POST /api/webhook with the event type and your endpoint URL

3. Your endpoint will start receiving HTTP POST requests when matching events occur

See the API Reference page for detailed endpoint documentation and curl examples.

📨 HTTP Request Format

Every webhook delivery is an HTTP POST request to your registered URL.

Headers included with every request:

• Content-Type: application/json; charset=utf-8 - the payload is always JSON

• X-OE-Webhook-Id: {id} - a unique identifier for this specific delivery (use this for idempotency and deduplication)

Conditional header:

• X-OrderEazi-UserId: {userId} - included only when the webhook is registered by an installed app. This identifies which OrderEazi user context the event belongs to.

📅 Date Format

All dates in webhook payloads use ISO 8601 sortable format.

Example: 2024-01-15T10:30:00

This applies to all Created, Modified, and other date fields across every payload type.

🔑 Authentication Context

Webhooks are registered under an API key. The API key determines which events you can subscribe to and what permissions you have.

If the API key belongs to an installed app, the X-OrderEazi-UserId header is automatically included in every dispatch. This allows your receiving application to identify the tenant context - particularly important for multi-tenant integrations.

✅ Summary

• OrderEazi sends HTTP POST requests with JSON payloads when events occur

• You register webhooks via the API, specifying the event type and your endpoint URL

• Every request includes a unique X-OE-Webhook-Id header for deduplication

• Installed app webhooks also include X-OrderEazi-UserId for tenant identification

• Failed deliveries are retried up to 3 times automatically

• All dates use ISO 8601 sortable format