Webhooks troubleshooting

Most webhook problems come down to one of a few causes: a slow or non-2xx response, a signature that doesn't match, or a secret that's out of sync after rotation. Work through the cases below.

My endpoint is marked "failing"

An endpoint flips to "failing" after the 7th failed delivery attempt (retries run over roughly 32 hours). It stays enabled — Hoursmith keeps sending new events. Check, in order:

• Response code and timing. Your endpoint must return a 2xx within ~10 seconds. Anything slower, or any non-2xx status, counts as a failure. Return 2xx fast and process asynchronously.
• Signature verification. A failing signature check that returns 4xx looks like a failed delivery — see the section below.
• Reachability. Confirm the URL is publicly reachable over HTTPS and isn't blocked by a firewall or returning 5xx under load.

Once the receiver is healthy, send a test event and replay any deliveries you missed. You don't need to recreate the endpoint.

See also: My webhook is failing.

Signatures don't match

If verification fails for every delivery, check these in order:

• Raw body. Verify against the raw request body bytes, before any JSON parsing or re-serialization. Re-stringifying the JSON changes the bytes and breaks the HMAC.
• Signed string. The HMAC is computed over `<t>.<rawBody>` — the timestamp from the header, a literal ., then the body. Don't forget the t. prefix.
• The right secret. Make sure you're using this endpoint's current signing secret. If you recently rotated, the old secret stops working immediately.
• Timestamp tolerance. Deliveries with a t more than 300 seconds (5 minutes) old are rejected as replays. If valid deliveries are rejected, check that your server clock is accurate (use NTP).

Full walkthrough with code: Verify signatures.

Deliveries time out

If deliveries are recorded as failed but your handler eventually finishes:

• Your endpoint is likely exceeding the ~10-second timeout. Acknowledge with a 2xx immediately, then process the event in a background job or queue.
• Avoid doing slow work — external API calls, large database writes — inline in the request handler.

I'm seeing duplicate events

Duplicates are expected: retries and replays reuse the same event id.

• Make your handler idempotent by deduping on the event id.
• Record the id before processing, and treat a repeat id as a no-op.

Signatures fail right after rotating

There is no dual-signing window when you rotate a secret — the old one stops working at once.

• Update your receiver's secret in lockstep with the rotation.
• Then send a test and replay any deliveries that failed during the switch. See Rotate the signing secret.

I can't find an old delivery

Delivery history is pruned automatically: succeeded deliveries are kept ~30 days, failed deliveries ~90 days. Older deliveries won't appear and can't be replayed.

Still stuck?

If your endpoint returns 2xx quickly and signatures verify but it's still marked failing, email hi@hoursmith.app.