Webhook trigger
A webhook trigger fires an email journey when an external system sends an HTTP request to the platform. When the payload is malformed, the API key expires, or the event stops firing, the journey stalls without alerting.
Definition
What a webhook trigger is
A webhook is an HTTP POST request sent from one system to another when an event occurs. In email journeys, the external system sends a webhook to the ESP to start a triggered flow. The request includes a payload with subscriber data and event details. The ESP receives the request, validates it, and enrols the subscriber in the journey.
Common use cases include purchase confirmations, account creation, password resets, and subscription upgrades. The e-commerce platform completes the order, sends a webhook to the ESP with the order details, and the confirmation email fires. The flow depends on the webhook arriving correctly and on time.
How it breaks
Common webhook failure modes
Malformed payload
The external system sends a request with missing fields, incorrect data types, or invalid JSON. The ESP rejects the request, and the journey never starts.
API key revoked
The authentication key expires or is rotated in the external system but not updated in the webhook configuration. The ESP returns a 401 error, and the request fails silently.
Timeout
The ESP endpoint is slow or unavailable. The external system retries once or twice, then gives up. The event occurred, but the email never fires.
Event stops firing
A code change in the external system removes the webhook call. The journey sits idle, waiting for requests that will never arrive. No error appears because nothing is attempting to send.
Why the platform does not catch it
Webhooks fail outside the ESP
The ESP only sees the requests that reach its endpoint. If the external system stops sending webhooks, or if the authentication fails before the request arrives, the ESP has no visibility into the problem. The journey appears healthy in the interface. All historical sends completed successfully. But no new subscribers are enrolling, and no alerts fire.
I worked with a business where a payment processor upgraded its API version and deprecated the old webhook signature format. The new format required a different header field. The upgrade happened on a Friday afternoon. The ESP rejected every inbound request with a 400 error. Payment confirmations stopped sending. The payment processor logged the failures internally, but the ESP showed nothing because the requests never made it past authentication. The first signal was customer complaints on Monday morning asking where their receipts were.
How monitoring catches it
Heartbeat checks detect absence
Heartbeat monitoring watches for the expected pattern of sends. If a webhook-triggered journey normally fires 20 times per hour, and suddenly no sends occur for 90 minutes, the pattern breaks. Telltide monitors detect the absence of the expected send and alert before customers notice.
For lower-volume flows, end-to-end checks work better. A test identity in the external system triggers a webhook at a set interval. The monitor watches for the corresponding email in the inbox. If the email does not arrive within the expected window, the webhook path is broken somewhere, and the alert fires.
Prevention
How to reduce webhook failures
- Log every outbound webhook request in the external system, including response codes and retry attempts.
- Set up alerts in the external system for any webhook endpoint that returns a non-200 status code more than twice in a row.
- Use a webhook testing service during development to validate payload structure before pointing at the live ESP endpoint.
- Store API keys in environment variables or a secrets manager. Never hard-code them in the application.
- Test the webhook path after every deployment that touches the code responsible for sending the request.
Related terms
Concepts that travel with webhooks
- Triggered flow: the email journey that starts when the webhook arrives.
- Journey step: the individual actions inside the flow, including delays and condition checks after the webhook trigger.
- Merge tag: often populated with data passed in the webhook payload.
- Heartbeat monitoring: the monitoring pattern that detects when expected webhook-triggered sends stop arriving.
Monitor webhook-triggered journeys from the inbox
One monitor free. Paid plans from $49 USD per month.