Use this guide when you are building a webhook receiver for Enad. It covers when to use Events, how delivery works, and what a receiver must handle.

Use Event catalog for exact event_type strings, envelope fields, schema IDs, and payload summaries. Use the JSON Schema contract for nested payload validation.

When to use Events

Use Events when another system should react after Enad changes:

• refreshing storefront, CDN, or search caches after catalog changes.
• sending product, variant, price, or stock changes to external systems.
• updating search indexes, feeds, or downstream records.
• alerting teams or starting reconciliation jobs.

Events complement APIs. Use APIs when you need to fetch current state, perform writes, run a backfill, or reconcile an event-driven integration after a missed or delayed delivery.

Events are separate from integration management. Use Integrations to list, create, update, delete, verify, inspect, or run sync work for an integration record. Use Events when a receiver should react after Enad data changes.

Webhook subscription groups

Webhook integrations currently accept these enabled_events groups:

Do not derive event names from this table. Use Event catalog for exact event_type strings, payload schema IDs, and top-level payload field summaries. Build nested payload validators from the JSON Schema contract.

Webhook integration configuration uses enabled_events values, not event type strings. Accepted values are attributes, brands, categories, markets, organisations, prices, products, series, stocks, store_groups, tags, users, and variants. These values gate delivery for the configured webhook integration; they are not a replacement for the event catalog.

Delivery behavior

Webhook delivery is POST over JSON. Each delivery body is wrapped as:

{
  "id": "2f4c8d75-6cf4-4c8a-9498-52e5fb21f4cb",
  "correlation_id": "8bb2e928-c5e1-45e2-aaf1-9136c4b6e6c1",
  "created_at": "2026-07-02T10:30:00.000Z",
  "event_type": "order.updated",
  "producer": "orders",
  "app_id": "7f3e1a3c-8c35-4f9f-a8e9-f8d766eecf3b",
  "payload": {
    "id": "6b35c4de-fd57-4a13-a6cb-322a3f77d142",
    "order_status": "processing",
    "reference": "ENAD-10001"
  }
}

This example uses the catalog-backed order.updated event and its Order Payload schema. The payload excerpt is not a full contract; use Event catalog before validating or mapping a production delivery.

Every delivery includes:

Authentication uses the configured custom auth header pair when one is configured. The current delivery shape does not add a signature header, so receiver implementations should not require a signing algorithm unless a delivery reference or webhook settings define one.

Treat the custom auth header as an app-level shared secret check. Reject the request before parsing or queuing work when the header is missing or different. Do not derive authentication from the payload body, event_type, catalog schema ID, timestamp fields, retry state, or X-Correlation-ID.

Return 2xx only after the receiver has safely accepted the delivery. A non-2xx response is failed and retryable.

Webhook delivery uses these retry waits:

After the retry budget is exhausted, the delivery is marked failed. DNS failures and direct private or loopback IP targets fail permanently. The current HTTP delivery client has a 10-second request timeout and does not follow redirects automatically.

Delivery states are pending, processing, completed, failed, and to-be-retried.

Receiver design

Keep the request path short:

1. Receive the webhook request.
2. Validate the configured custom auth header when one is configured.
3. Validate that the body can be parsed without assuming payload fields outside the Event catalog and JSON Schema contract.
4. Persist or enqueue the raw delivery and relevant metadata.
5. Return 2xx only after the delivery is safely accepted.
6. Queue slow work, external API calls, and downstream retries for a background worker.
7. Reconcile with Enad APIs when ordering, missing data, or freshness matters.

Idempotency, ordering, and freshness

Your receiver should tolerate duplicate, delayed, and reordered deliveries:

• store a deduplication key before processing business logic.
• keep deduplication state long enough to cover the retry window and downstream lag.
• fetch current state from the appropriate API before overwriting important downstream records.
• design handlers as upserts rather than blind increments.
• run scheduled reconciliation jobs for business-critical syncs.

Error handling

Treat receiver failures as operational signals:

• reject unauthenticated requests before queuing work.
• log parse errors, unknown event families, and unsupported catalog versions.
• separate acceptance failures from downstream processing failures.
• expose metrics for accepted, rejected, queued, failed, and deduplicated deliveries.
• keep enough raw delivery data to debug without storing sensitive secrets unnecessarily.

Registration and operations

Webhook integrations are configured with an endpoint, enabled subscription groups, custom auth header settings, optional delay, and optional store-group scope. Before production, confirm:

• which event-family groups are enabled.
• which receiver URL is configured.
• whether a custom auth header is configured.
• whether a delivery delay is configured.
• whether store-group scope is configured.

Pairing events with APIs

Events tell you something changed. APIs let you verify what is true now.

Quick reference