My webhook is failing
Webhook endpoint marked "failing"? It must return 2xx within ~10s and pass signature verification. Webhooks need the Agency plan.
A webhook endpoint gets marked "failing" when it stops returning success. The cause is almost always a slow or non-2xx response, or a signature check that doesn't match. Let's narrow it down.
Most likely cause
Webhooks require the Agency Agency plan. Your endpoint must return a 2xx response within about 10 seconds. When deliveries fail, Hoursmith retries 7 times over roughly 32 hours, then marks the endpoint "failing" — note it stays enabled. Signature problems are the other frequent cause.
How to check
- Confirm the plan. Webhooks are Agency-only.
- Response code and timing. Make sure your receiver returns 2xx within ~10 seconds; anything slower or non-2xx counts as a failure.
- Signature. Verify the
Hoursmith-Signatureheader (formatt=...,v1=...), an HMAC-SHA256 overt.body, and that the timestamp is within the 5-minute window. - Secret rotation. There is no dual-sign window when you rotate the secret — if your receiver still uses the old secret, every verification fails.
How to fix
Return 2xx quickly
Acknowledge the delivery with a 2xx immediately and do heavy work asynchronously, so you respond within the ~10-second budget.
Fix signature verification
Recompute HMAC-SHA256 over t.body and compare against v1 in the Hoursmith-Signature
header. Reject anything outside the 5-minute window — and make sure your clock is accurate.
Update the secret in lockstep
If you rotated the signing secret, update your receiver at the same time — there's no overlap period where both secrets are accepted.
Replay and re-test
Once your endpoint is healthy, use Replay to re-deliver missed events and Send-test from the UI to confirm it's working.
A "failing" endpoint is still enabled — fix the receiver, send a test, and it resumes delivering. You don't need to recreate it.
Still stuck?
If your endpoint returns 2xx fast and signatures verify but it's still marked failing, email hi@hoursmith.app. References: Webhooks troubleshooting, Verify signatures, and Retries & replay.
API token issues
Getting 401, 402, 403, or 429 from the Hoursmith API? Each maps to a specific cause — bad token, plan, role, or rate limit. Here's how to fix each.
MCP won't connect
The Hoursmith MCP server needs HOURSMITH_API_TOKEN (starting hsk_) and a Studio or Agency plan, Node 18+, and a restart after editing config.