Skip to content

Monitor and recover webhooks

Understand retries, recover a failing or disabled webhook, and regenerate signing secrets.

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. 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. 2.

    Fix the receiver

    Correct signature handling, availability, rate limiting, or timeouts.

  3. 3.

    Send a test

    Choose Send test and confirm the receiver returns 2xx. A successful test resets the failure count.

  4. 4.

    Enable the webhook

    If the webhook was disabled, choose Enable from its actions menu. Enable stays unavailable until a test succeeds.

The delivery log in the app is read-only. To resend an individual delivery, use the retry endpoint in the Webhooks API. To catch up after an outage, replay the events from the last 30 days with the replay endpoint or 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. 1.

    Prepare the receiver

    Make sure its secret can change without a code edit.

  2. 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. 3.

    Copy the new value

    Save the new signing secret before closing the dialog. It is not shown again.

  4. 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.

If you lose the new secret before storing it, regenerate it again. Never share a signing secret in a post, task, chat message, or support request.

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.
Image preview
100%