Webhooks and Notifications

Webhooks

Alloy's Journeys support end-to-end onboarding processes that often involve asynchronous steps — Manual Reviews, Step-Up verification, and long-running data services can all introduce delays between initial submission and final outcome. Configuring a webhook endpoint is critical for handling these gracefully.

Webhooks increase resiliency because:

• You receive real-time updates as Journey Applications progress, without polling.
• Downstream processing can be decoupled from the synchronous API response.
• In scenarios where processing is delayed, webhooks ensure you receive the final outcome without holding an open connection.

Alloy supports sending a webhook for any status change in the Journey Application lifecycle. For a full list of event types, see Journey Status Webhook Events in Alloy's public documentation.

Endpoint Design Best Practices

Acknowledge immediately, process asynchronously. Return a 2xx HTTP status code as quickly as possible upon receipt — before any processing logic runs. This prevents Alloy from treating the delivery as failed due to a timeout. If Alloy times out or receives a 4xx/5xx, it will automatically retry on an exponential backoff schedule. Process the payload in a background job or queue after acknowledging.

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.

Only subscribe to events you care about. Alloy's Journey webhook event type supports many possible Journey statuses, but many may not be pertinent to your integration. Filtering out statuses you don't need prevents unnecessary backlogs or delays due to high traffic.

Monitor for delivery gaps. Track webhook receipt timestamps against Journey Application submission timestamps to detect if your endpoint is failing to receive events.

Handling Delayed Delivery

Some Journey Application workflows 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 can usually be replayed and delivered even after a significant delay. However, in very rare cases they may not be replayable. To protect against this, implement infrequent polling as a fallback using the Get Journey Application endpoint.

Rule-Based Notifications

Alloy's Rule-Based Notifications (RBN) feature allows you to configure custom, Workflow- and Journey-specific rules to proactively alert when key metrics cross a specific threshold. RBN is especially useful for closing monitoring gaps quickly in the early stages of an integration, before full programmatic instrumentation is in place. For more information on RBN, check out Rule-Based Notifications.