From 75a9694e630f958e220ae17bf004b3b6ab3134dc Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Sat, 15 Aug 2026 10:53:52 +0530 Subject: [PATCH 1/2] docs: UZ-WH-020 states both causes, and the fix names a real field The row said the workspace lacks the named secret. That is one of two causes. The trigger's source can also be unknown to the provider registry, and the middleware answers UZ-WH-020 for both. The fix column pointed at secret_ref, a field from the Svix path. A manual webhook trigger resolves credential_name, which defaults to the source name. The row now names the field the reader's TRIGGER.md actually has. error-codes.mdx is regenerated from the registry, whose UZ-WH-020 entry now states the fact before the fix like every other row. The verified stamp moves forward with the regeneration. Co-Authored-By: Claude Opus 5 (1M context) --- api-reference/error-codes.mdx | 4 ++-- fleets/webhooks.mdx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index d1e4268..6030312 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -3,7 +3,7 @@ title: Error codes description: API error response fields and stable error codes. type: reference audience: user -verified: 2026-08-14 +verified: 2026-08-15 product_version: 0.26.2 executable: false --- @@ -114,7 +114,7 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-WH-002` | 400 | Malformed webhook | Webhook payload could not be parsed. Check Content-Type and body. | Keep webhook signing secrets matched and service clocks synchronized. | | `UZ-WH-010` | 401 | Invalid webhook signature | The webhook signature did not verify. The stored signing secret must match the one configured upstream. | Keep webhook signing secrets matched and service clocks synchronized. | | `UZ-WH-011` | 401 | Stale webhook timestamp | The webhook timestamp is more than 5 minutes off. That means a replay or clock skew. | Keep webhook signing secrets matched and service clocks synchronized. | -| `UZ-WH-020` | 401 | Webhook credential not configured | Create a random webhook secret of at least 32 bytes. Store it as this source's webhook_secret, set the same value upstream, then resend. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-020` | 401 | Webhook credential not configured | This source is not a recognized webhook provider, or the workspace holds no webhook secret for it. Create a random secret of at least 32 bytes, store it as the source's webhook_secret, set the same value upstream, then resend. | Keep webhook signing secrets matched and service clocks synchronized. | | `UZ-WH-021` | 404 | Connector installation is not mapped | Reconnect the provider App to the intended workspace, then redeliver the event. | Keep webhook signing secrets matched and service clocks synchronized. | | `UZ-WH-022` | 404 | No fleet subscription matched | Bind the repository and event to an active fleet with an approved integration grant. | Keep webhook signing secrets matched and service clocks synchronized. | | `UZ-WH-030` | 413 | Webhook payload too large | The webhook body exceeds the 1 MiB limit. Reduce the payload size. | Keep webhook signing secrets matched and service clocks synchronized. | diff --git a/fleets/webhooks.mdx b/fleets/webhooks.mdx index 67cf7d8..ced5e10 100644 --- a/fleets/webhooks.mdx +++ b/fleets/webhooks.mdx @@ -3,7 +3,7 @@ title: Configure a webhook description: Send signed provider events to a fleet. type: how-to audience: user -verified: 2026-07-12 +verified: 2026-08-15 product_version: 0.26.2 executable: false --- @@ -76,7 +76,7 @@ A successful request returns HTTP `202`. A filtered or inactive event returns HT | `UZ-WH-001` | The fleet URL is wrong or deleted. | Copy the current URL from the fleet. | | `UZ-WH-010` | The signature does not match. | Use the same signing secret on both sides. | | `UZ-WH-011` | The signed timestamp differs by more than 5 minutes. | Correct the sender clock. | -| `UZ-WH-020` | The workspace lacks the named secret. | Create the `secret_ref` name. | +| `UZ-WH-020` | The trigger's `source` is not a supported provider, or the workspace has no secret for it. | Use a supported `source`. Create the workspace secret named by `credential_name`, which defaults to the `source` name. | | `UZ-WH-030` | The body exceeds 1 MiB. | Filter or shorten the provider body. | Providers can deliver the same event more than once. Use a stable provider event identifier and make fleet actions safe to repeat. From 22af4373285ed0dfc790cbb5b39963ab8578a66c Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Sat, 15 Aug 2026 12:16:36 +0530 Subject: [PATCH 2/2] docs: a secret cannot make an unsupported source supported MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Greptile, twice and correctly. UZ-WH-020 has two causes and the remedy answered only one: creating a secret does nothing when the trigger's source is not a recognized provider, so the sender resends and gets UZ-WH-020 again. Both rows now name the recognized sources — github, slack, linear (webhook_verify.zig) — before the secret step. The webhooks row also never said where the signing value goes. It is the secret's webhook_secret field (serve_webhook_lookup.zig reads exactly that field); storing it under another property leaves the verifier unable to find it. error-codes.mdx is regenerated from the corrected registry entry, which ships in agentsfleet PR #603. The registry string is split into three sentences so the generated row clears this repository's 25-word DOC-02 check, which caught it at 26. Co-Authored-By: Claude Opus 5 (1M context) --- api-reference/error-codes.mdx | 2 +- fleets/webhooks.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index 6030312..570dd0f 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -114,7 +114,7 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-WH-002` | 400 | Malformed webhook | Webhook payload could not be parsed. Check Content-Type and body. | Keep webhook signing secrets matched and service clocks synchronized. | | `UZ-WH-010` | 401 | Invalid webhook signature | The webhook signature did not verify. The stored signing secret must match the one configured upstream. | Keep webhook signing secrets matched and service clocks synchronized. | | `UZ-WH-011` | 401 | Stale webhook timestamp | The webhook timestamp is more than 5 minutes off. That means a replay or clock skew. | Keep webhook signing secrets matched and service clocks synchronized. | -| `UZ-WH-020` | 401 | Webhook credential not configured | This source is not a recognized webhook provider, or the workspace holds no webhook secret for it. Create a random secret of at least 32 bytes, store it as the source's webhook_secret, set the same value upstream, then resend. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-020` | 401 | Webhook credential not configured | The trigger's source is not a recognized webhook provider (github, slack, linear), or the workspace holds no secret for it. Set a recognized source. Then store a random value of at least 32 bytes in that secret's webhook_secret field, set the same upstream, and resend. | Keep webhook signing secrets matched and service clocks synchronized. | | `UZ-WH-021` | 404 | Connector installation is not mapped | Reconnect the provider App to the intended workspace, then redeliver the event. | Keep webhook signing secrets matched and service clocks synchronized. | | `UZ-WH-022` | 404 | No fleet subscription matched | Bind the repository and event to an active fleet with an approved integration grant. | Keep webhook signing secrets matched and service clocks synchronized. | | `UZ-WH-030` | 413 | Webhook payload too large | The webhook body exceeds the 1 MiB limit. Reduce the payload size. | Keep webhook signing secrets matched and service clocks synchronized. | diff --git a/fleets/webhooks.mdx b/fleets/webhooks.mdx index ced5e10..58b76a1 100644 --- a/fleets/webhooks.mdx +++ b/fleets/webhooks.mdx @@ -76,7 +76,7 @@ A successful request returns HTTP `202`. A filtered or inactive event returns HT | `UZ-WH-001` | The fleet URL is wrong or deleted. | Copy the current URL from the fleet. | | `UZ-WH-010` | The signature does not match. | Use the same signing secret on both sides. | | `UZ-WH-011` | The signed timestamp differs by more than 5 minutes. | Correct the sender clock. | -| `UZ-WH-020` | The trigger's `source` is not a supported provider, or the workspace has no secret for it. | Use a supported `source`. Create the workspace secret named by `credential_name`, which defaults to the `source` name. | +| `UZ-WH-020` | The trigger's `source` is not a supported provider, or the workspace has no secret for it. | Supported sources are `github`, `slack`, and `linear`. Create the workspace secret named by `credential_name`, which defaults to the `source` name, and put the signing value in its `webhook_secret` field. | | `UZ-WH-030` | The body exceeds 1 MiB. | Filter or shorten the provider body. | Providers can deliver the same event more than once. Use a stable provider event identifier and make fleet actions safe to repeat.