Skip to main content

​
Overview

When a webhook delivery fails, Extole sends a notification in the Technical category and records the attempt in the webhook’s Live View under Tech Center > Outbound Webhooks. Four of the alerts share one message text, so the alert’s name is what tells you which part of the delivery failed. This page explains how one delivery attempt works, what each alert means, how retries are scheduled, and how to read the Live View.

​
How a Delivery Attempt Works

Every attempt runs the same four steps:
  1. Build the request. Extole evaluates the webhook’s request expression, builds the HTTP request, and checks the URL. A failure here sends an alert and no request is sent.
  2. Send it. Extole sends the request and waits up to 20 seconds for a response.
  3. Run the response handler. If the webhook has a response_handler expression, Extole evaluates it. This step runs even when no request was sent. A response handler can return only OK or RETRY.
  4. Decide the outcome.
    • If the handler returned OK, the attempt succeeds. The HTTP status is not checked, so a handler that returns OK for a 500 response hides that failure.
    • If the handler returned RETRY, the attempt is retried.
    • If the handler returned nothing, because there is no handler or because it failed, only a 2xx status counts as success. A 3xx status is a failure here too.
A failed attempt is retried, whatever step it failed in. One failed attempt can therefore raise two alerts: the alert from the step that failed, and webhook_missing_status_failure from step 4, because no status was recorded.

​
The Retry Schedule

Extole tries a delivery up to four times: right away, then 30 seconds, 1 hour, and 3 hours after each failure. After the fourth failure the event is set aside and is not retried. A webhook can carry its own retry_intervals in place of this schedule. The attempt_count on a dispatch result starts at 0, so the four attempts are numbered 0 to 3.
An edit to a webhook’s request or response_handler expression has no draft and no publish step. The next attempt uses the new expression, and that includes retries of events that failed before the edit.

​
The Alerts

The first four alerts in the table, plus webhook_invalid_status_failure, carry the same message: “We couldn’t send an event for the webhook name webhook. Please see here for more information”, followed by a link to the webhook’s page. Read the alert name, not the message, to tell them apart. On the final attempt the retrying alert still says “retrying”, but nothing further is retried. Every webhook alert carries the tags technical and webhook: followed by the webhook’s id, which places it in the Technical category of My Extole notifications.

​
Reading the Live View

Open Tech Center > Outbound Webhooks, select the webhook, and find Webhook Live View. The Dispatch Results tab lists recent attempts with their Time, Response Code and Response Message, and a filter for All Response Codes, one entry per code, and No Response for attempts with no status. Select a row to see the whole dispatch result:
  • url, method, request_body and request_headers: what was sent, or what would have been sent when the send itself failed. Authorization headers and bearer or basic tokens in the body are hashed before they are stored. Other headers, such as an API key header, are stored as sent.
  • response_status_code, response_body and response_headers: what came back. All three are empty when no response arrived.
  • attempt_count: 0 for the first attempt.
  • webhook_event_id: the same for every attempt at one event. Group by it to count failures as events rather than attempts.
  • log_messages: the errors from that attempt.
The list shows the 50 most recent results by default. The same results are available from the API at /v6/webhooks/, the webhook’s id, /dispatch-results/recent, with limit and offset parameters, and the request is logged even when it failed to send.

​
What the Log Messages Mean

A webhook’s client_key_id is its default key, used for the default request and for a client certificate. An empty client_key_id does not mean the expression uses no stored key, because an expression can name any stored key by id.

​
What to Do

  • A compile or run-time error in request or response_handler: fix the expression. The next attempt, including the retries already queued, uses the new expression.
  • webhook_invalid_status_failure with a 4xx status: the destination rejected the request. Read response_body for the field or rule it names, and compare request_body with what the destination expects.
  • A 5xx status or webhook_dispatch_failed: see Handling 5xx Responses. Keep your endpoint’s response under 20 seconds, and return 2xx as soon as the event is stored.
  • webhook_response_handler_retrying_request on every attempt: the handler’s RETRY condition matches a permanent failure. Narrow the condition so a permanent error is reported instead of retried.
  • A client key= error: check the key under Security Center, and the credentials at the provider it points at.
  • Alerts with no matching dispatch result: a busy webhook can push the failing attempt past the first page. Page further back with offset, or filter by response code.