Webhooks Overview

Flex can notify your system of events in real-time via outbound webhooks. When a relevant event occurs, Flex sends an HTTP POST request containing a JSON payload to your registered endpoint URL.

General Contract

All webhook deliveries follow these rules:

Property	Detail
Method	`POST`
Content type	`application/json`
Timeout	10 seconds
Acknowledgement	Your endpoint must return a `2xx` status code
Retry policy	Failed deliveries (non-`2xx` or timeout) are retried with exponential backoff for up to 24 hours
Delivery guarantee	At-least-once
Ordering guarantee	None

Idempotency

Because delivery is at-least-once, your handler must be idempotent. The same event may be delivered more than once. Use the top-level id field to deduplicate.

{
  "id": "evt_abc123",
  "date": "2026-04-15T08:30:00Z",
  "field1": "...",
}

Ordering

Events may arrive out of order. For events where timing matters (e.g. preference changes), use the date field to determine whether the payload should be applied or discarded.

Example: Your system receives two customer.preference_updated events for the same customer. Compare the date values and discard the older one for the same customer, channel and group/outlet context:

Event A  date: 2026-04-15T08:30:00Z   <-- discard (older)
Event B  date: 2026-04-15T08:31:12Z   <-- apply  (newer)

Asynchronous Processing

We recommend processing webhook payloads asynchronously. Accept the request, return a 200 response immediately, and process the payload on a background worker. This avoids hitting the 10-second timeout on heavier workloads.

Security

Refer to Signature Verification for details on validating that incoming requests originated from Flex.

API Reference

Refer to the API Reference (Webhooks section) for the full list of event types, payload schemas, and configuration endpoints.