Best Practices

Return a 200 success response

Your endpoint should always acknowledge webhook requests with a 200 success response. Alloy interprets 4xx/5xx responses as a failure to deliver the webhook and will continue retrying until the webhook receives a success response or reaches the retry limit.

Process webhooks asynchronously

Your endpoint should respond to webhook requests quickly and then process the event asynchronously. Alloy webhooks have a 10-second timeout for the entire request. If a response is not received within 10 seconds, the request is considered failed and will be automatically retried.

Only subscribe to events your integration requires

Webhooks related to Journey changes are triggered by all of your Journeys and Journey application events by default. Alloy recommends specifying the Journeys and events that your integration should be notified about to prevent unnecessary webhook requests.

Don't rely on webhooks arriving in order

It is not guaranteed that webhooks will arrive in the order in which they occur. Alloy recommends that your integration be designed in a way that does not rely on ordered arrival.

Design for idempotency

Alloy may deliver the same webhook event more than once (e.g., due to network issues during delivery). Your handler should be able to process duplicate events safely without creating duplicate records or triggering duplicate actions.

Handling Delayed Delivery

Some Journeys involve steps that take meaningful time. Do not assume a final outcome will arrive within a fixed time window. Build your downstream systems to handle open and pending states for extended durations.

In the rare event of an Alloy outage, webhooks are usually replayed and delivered even after a significant delay.