Monitor and recover webhooks
Understand retries, recover a failing or disabled webhook, and regenerate signing secrets.
- PlanPro or Enterprise
- WhoOwners, admins, and members
Design the receiver for delivery
- Verify the signature before doing any work.
- Return a 2xx response within 30 seconds after the delivery is accepted for processing.
- Use the event ID in webhook-id (also sent as X-Webhook-Id) as an idempotency key. It is unique for each event and stays the same on every retry.
- Do not depend on strict delivery ordering.
Retries and automatic disabling
- Retries
- Network failures, HTTP 429, and HTTP 5xx responses are retried, up to 10 delivery attempts over about 3 days. Other unsuccessful responses are not retried, and a redirect counts as a failure because Project Feed never follows one. See the Webhooks API reference for the retry schedule. A webhook that starts an AI agent run retries less, because a retry can start a second run; see Start AI agent runs.
- Automatic disabling
- After 10 consecutive failed delivery attempts within 24 hours, Project Feed disables the webhook and its row shows Disabled after repeated failures. A successful delivery resets the count. A 410 Gone response disables the webhook at once, because it means the endpoint was removed.
Recover a failed or disabled webhook
- 1.
Check the delivery log
Open the webhook's actions menu and choose View deliveries. The log shows the last 20 deliveries with their response status, duration, and error.
- 2.
Fix the receiver
Correct signature handling, availability, rate limiting, or timeouts.
- 3.
Send a test
Choose Send test and confirm the receiver returns 2xx. A successful test resets the failure count.
- 4.
Enable the webhook
If the webhook was disabled, choose Enable from its actions menu. Enable stays unavailable until a test succeeds.
pf webhooks replay. A replayed event keeps its original event ID, so a receiver that deduplicates on it sees a repeat.Regenerate a signing secret
- 1.
Prepare the receiver
Make sure its secret can change without a code edit.
- 2.
Regenerate the secret
Choose Regenerate secret from the webhook's actions menu and confirm. The webhook-signature header carries signatures from both secrets for 24 hours. Legacy X-Webhook-Signature uses the new secret immediately.
- 3.
Copy the new value
Save the new signing secret before closing the dialog. It is not shown again.
- 4.
Deploy and test
Update the receiver's secret, deploy it, and choose Send test to confirm verification. After 24 hours only the new secret signs webhook-signature.
Fix delivery problems
- Deliveries stop arriving
- Check whether the row shows Disabled or Disabled after repeated failures, then follow the recovery steps above.
- Deliveries are slow or time out
- Return 2xx within 30 seconds. Move slow work to a queue and acknowledge the delivery first.