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
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.
terminalhooksmith logs hooksmith logs orders-to-api
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.
terminalhooksmith open orders-to-api
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.yamlapiVersion: 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: secretterminalhooksmith deploy orders-to-api
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.
terminalhooksmith secrets set DESTINATION_URL hooksmith edit orders-to-api hooksmith deploy orders-to-api
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:
terminalhooksmith replay <event-id>
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.
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.