Best practices

Respond quickly. Return a 200 response as soon as you receive the webhook, then process it asynchronously. If your handler takes too long, the delivery will time out and be retried, potentially causing duplicate processing.

Use the event ID for idempotency. The id field in the payload is a unique identifier for each event. Store processed event IDs and skip duplicates. Retries send the same id, so this prevents processing the same event twice.

Verify signatures. Always validate the X-Webhook-Signature header before trusting the payload. This confirms the request came from Sotion and wasn't modified in transit.

Use HTTPS. Webhook URLs must use HTTPS. HTTP endpoints are rejected.

Handle events you don't recognize gracefully. New event types may be added in the future. If you receive an event type you don't handle, respond with 200 and ignore it. Don't return an error code, or it will be retried unnecessarily.

Don't rely on delivery order. While events are generally delivered in the order they occur, this is not guaranteed. Use the timestamp field if ordering matters to your integration.