Skip to content

Guide

How to retry, replay and debug failed webhook deliveries

Run hooksmith logs to find the event, then open it in the dashboard to read each attempt: the HTTP status, the error, and the request and response bodies. Fix the cause. Then use Retry delivery to resend the stored outbound request to one destination, or Replay event (hooksmith replay <event-id>) to run the original request through the hook's current config as a new event. Hooksmith retries network errors, timeouts, 5xx, 408, 425 and 429 on its own, and fails other 4xx responses at once.

Before you start

  • The Hooksmith CLI, installed and logged in (curl -fsSL https://hooksmith.tech/install.sh | bash, then hooksmith login).
  • A deployed hook that has received at least one event. If a delivery has not failed yet, the steps still show where to look.

Steps

  1. Step 1: Find the failing event

    hooksmith logs prints the 50 most recent events across your hooks. Pass a hook name to see only that hook. Each line has the time, the status, a label, the event id and the last error.

    An event status is one of received, deferred, retrying, delivered, partial, failed or skipped. retrying means a delivery failed and the next attempt is scheduled. failed means every attempt is used up, or the error cannot be retried. partial means some destinations succeeded and some did not.

    terminal
    hooksmith logs
    hooksmith logs orders-to-api
  2. Step 2: Read the attempts in the dashboard

    hooksmith open orders-to-api prints the dashboard URL for the hook and opens it. Select the event in the hook's Recent events, or in Logs. Each destination shows its state, HTTP status, duration, attempt count and error, with the request body Hooksmith sent and the response body it got back (the first 4,000 characters).

    Read the response body first. A destination that returns 401, 404 or a validation message usually tells you what is wrong.

    terminal
    hooksmith open orders-to-api
  3. Step 3: Set the retries and timeout you want

    A destination without a retries block follows the platform schedule: 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 3 hours, 6 hours, 12 hours and 24 hours. That is 9 retries after the first attempt.

    Set retries to choose your own. With backoff: exponential and initialDelay: 30s, the waits double: 30 seconds, 1, 2, 4 and 8 minutes for max: 5. With backoff: fixed, every wait is the initialDelay. No wait is longer than 24 hours, and a Retry-After header from the destination is honoured. timeout is capped at 30 seconds per attempt; the default is 8 seconds.

    Replace the contents of .hooksmith/hooks/orders-to-api.yaml with the hook below, then deploy it. Only network errors, timeouts, 5xx, 408, 425 and 429 are retried. Other 4xx responses and redirects fail at once, whatever max says.

    .hooksmith/hooks/orders-to-api.yaml
    apiVersion: hooksmith/v1
    kind: Hook
    metadata:
      name: orders-to-api
      description: Standard Webhooks events to an HTTP API
    spec:
      source:
        preset: standard-webhooks
      destinations:
        - name: primary
          url: ${DESTINATION_URL}
          method: POST
          timeout: 10s
          retries:
            max: 5
            backoff: exponential
            initialDelay: 30s
      transform:
        engine: handlebars
        fields:
          event: "{{type}}"
          id: "{{data.id}}"
      variables:
        - name: WEBHOOK_SIGNING_SECRET
          from: secret
        - name: DESTINATION_URL
          from: secret
    
    terminal
    hooksmith deploy orders-to-api
  4. Step 4: Fix the cause

    If the destination URL or a secret was wrong, set it again. Destination URLs and secrets are read again at every attempt, so retries that are still scheduled pick up the correction. The request body is built when the event arrives and does not change.

    If the transform was wrong, edit the hook and deploy it. That fixes future events. For events already received, use Replay in the next step.

    terminal
    hooksmith secrets set DESTINATION_URL
    hooksmith edit orders-to-api
    hooksmith deploy orders-to-api
  5. Step 5: Retry the delivery, or replay the event

    Retry delivery is a button on a failed delivery. It resends the stored outbound request to that one destination with a fresh retry budget. There is no new transform and no new event. Use it when the destination was the problem.

    Replay event re-runs the original request, with its raw body and stored headers, through the hook's current config. It creates a new event linked to the old one, skips the signature check and the duplicate check, and is not counted toward your monthly usage. Use it when the transform or conditions were the problem. From the terminal:

    terminal
    hooksmith replay <event-id>
  6. Step 6: Get told when a delivery fails for good

    Hooksmith emails the workspace when a delivery ends as failed, after its retries are used up. Intermediate failed attempts send nothing. There is at most one failure email per hook in each 60 minute window, then one recovery email when a delivery succeeds again.

    Recipients are the workspace owners, or up to 5 addresses you list. Owners change this in Settings, where Send test alert checks that the email arrives. Hooksmith for Mac also shows a notification for a failed delivery, at most one per hook every five minutes by default.

How to check it works

After the fix, confirm the whole path.

  • Replay the failed event with hooksmith replay <event-id>. The command prints the new event as JSON, including its status. It should be delivered.
  • hooksmith logs orders-to-api lists the new event as delivered. The original event keeps its failed status as a record.
  • In the dashboard, the Retry delivery path updates the same event: its status changes to delivered once the retried delivery succeeds.
terminal
hooksmith logs orders-to-api

Troubleshooting

  • HTTP 404 (or another 4xx) and no retries.

    4xx responses other than 408, 425 and 429 are permanent failures. Fix the URL or what the destination expects, then retry the delivery.

  • HTTP 301 redirect not followed (Location: ...)

    Hooksmith never follows redirects. Store the final URL as the destination.

  • timed out after 10000ms

    The destination did not answer in time. This is retried. Answer faster, or raise timeout up to the 30 second cap.

  • destination URL must use https, destination host localhost is not allowed, or destination resolves to a private address

    Destinations must be public HTTPS addresses. These errors are permanent. Use a public URL. For a service on your laptop, use the tunnel in Hooksmith for Mac instead.

  • DNS lookup failed for <host>

    The hostname did not resolve. This one is retried, so a temporary DNS problem recovers on its own.

  • Secret not found: DESTINATION_URL

    A secret the hook references is missing. At ingest the sender gets a 400. For deliveries already queued, retries continue until you store it with hooksmith secrets set.

  • ... (gave up after 6 attempts)

    The schedule is used up and the delivery is failed. Fix the cause, then choose Retry delivery to start a fresh budget.

  • This event was received with logging.retainPayload: false, so there is nothing to replay

    The request was not stored. Remove logging.retainPayload: false so future events can be replayed. Retry delivery still works, because each delivery keeps its own outbound request.

  • Hook orders-to-api is deleted (HOOK_DELETED), or Hook <id> is inactive (HOOK_INACTIVE)

    Replays and retries are refused for a deleted or inactive hook. Deploy it again with hooksmith deploy orders-to-api.

  • Not logged in, or the token was rejected.

    Run hooksmith login. This is what logs, events and replay print when the API answers 401 or 403.