Webhooks

Best practices for ESW webhooks: HTTPS and domain requirements, validate event type/version, respond within 3 seconds, and design for async delivery.

Use these guidelines when you subscribe to ESW webhooks and implement the receiving endpoint.

Endpoint requirements

• Subscriptions must point to an HTTPS endpoint. ESW rejects non-HTTPS endpoints.
• Webhook endpoints must be in the same domain as the origin checkout domain, or one of your registered domains.
• Keep SSL certificates valid and maintained. ESW will not deliver to endpoints with SSL issues (mismatch, untrusted cert, etc.).

Event types and versions

• ESW supports multiple event types. Each event type can include multiple actions.
• Over time, ESW may add new event types, add actions to existing event types, or release new versions.
• Always check the event type and event version before processing.
• Use the Esw-Event-Type request header to identify the received event and route it correctly.
• Expect test events. Handle them safely.

Acknowledge quickly

ESW expects a response within 3 seconds of delivering the payload.

If your service takes longer, the connection is terminated and the payload is re-queued.

• Do lightweight validation first.
• Offload heavy work to a background job/queue.

Delivery model and retention

Webhooks are delivered asynchronously. Delays can occur within the SLA, or longer in rare cases.

Do not use webhooks as a real-time event-sourcing mechanism.

ESW queues undelivered events. By default, queued events are stored for 24 hours. After that, events are dropped.

Design for retries, occasional duplicates, and out-of-order delivery. Keep handlers idempotent.