Configure a webhook

What this does

A webhook sends provider events to one fleet. agentsfleet verifies the request before creating an event. Connect a GitHub App to route its events to subscribed fleets. For a webhook you configure yourself, use the fleet URL listed in webhook_urls.

Before you begin

Create a workspace secret with the sender’s signing value in its webhook_secret field. For Svix, keep the full whsec_ value in that field. Use Secrets or the secrets command. Add a webhook trigger to the triggers list under config["x-agentsfleet"] in the fleet’s Definition.

{
  "type": "webhook",
  "source": "github",
  "repositories": ["owner/repository"],
  "events": ["pull_request"],
  "credential_name": "github"
}

Author a fleet shows the whole Definition and how to save it. source names the provider in lowercase letters, digits, and hyphens. It is also the last part of the fleet’s webhook URL. Two webhook triggers on one fleet cannot share a source, and approval is reserved. GitHub, Linear and Slack use their built-in signing rules. Other sources require a verifier object. Choose the recipe that matches your provider’s webhook guide. All three body recipes use SHA-256 with a Hash-based Message Authentication Code (HMAC), keyed by the stored signing secret. Other digest algorithms fail verification.

`scheme`	Signature format	`header`
`body-hex-sha256`	`sha256=` followed by hex over the raw body	required
`body-hex`	bare hex over the raw body	required
`body-base64-sha256`	standard padded base64 over the raw body	required
`slack-v0`	Slack version and timestamp	omitted; fixed Slack headers
`svix-v1`	Svix identifier and timestamp	omitted; fixed Svix headers

For example, a provider that sends a prefixed hex signature can use:

{
  "type": "webhook",
  "source": "acme",
  "credential_name": "acme-signing",
  "verifier": {"scheme": "body-hex-sha256", "header": "x-acme-signature"}
}

An authored header must be an HTTP token of 1–128 characters, without spaces. GitHub, Linear and Slack reject a verifier override. For a Svix sender, use "verifier": {"scheme": "svix-v1"} and store its whsec_ value in the named credential’s webhook_secret field. Trigger order does not affect routing. Verification accepts signed incoming events. You still register the URL with the sender; choosing a recipe creates no provider subscription or account access.

repositories is required when the event arrives through a connected GitHub App. One App delivery is offered to every fleet in the workspace. A fleet that names no repository has subscribed to nothing.The delivery is then answered 200 with {"ignored": "UZ-WH-022"}, so GitHub records it as successful and no run starts. Read the body, not the status.A delivery posted to the fleet’s own webhook URL does not need it. That URL already names the fleet and the source, so the sender chose both.

Omit events to accept every event type the path supports. List event names to accept only those types. The connected App starts runs for pull_request and failed workflow_run events. Workflow events must have action completed and conclusion failure. Events from repair branches are ignored. deployment_status, push, and issues start no run, even if you name them or omit events.

Steps

Choose the procedure for a connected GitHub App or a webhook URL you configure yourself.

A connected GitHub App

Save the fleet first. A grant belongs to a fleet, so the fleet has to exist before its grant can be approved.

Connect the provider once per workspace. Open the account menu and choose Connect apps. Choose GitHub and approve the access it requests. The workspace owns the connection.
Save a fleet whose webhook trigger names your repositories. A library entry cannot know your repository. Before you save, ask the chat to set repositories on the webhook trigger, or edit the Definition file, then review the change. <DRAFT_ID>, <NAME>, and <DIGEST> come from the review.
agentsfleet chat <DRAFT_ID> --no-input --save --name <NAME> --review-digest <DIGEST>
<varies> ✓ Fleet <NAME>: installing <varies>
Approve the fleet’s integration grant. Saving raises the grant, and the fleet reads installing until a person approves it with agentsfleet approvals. After the approval, run agentsfleet resume <FLEET_ID> to finish setup. The fleet then reads active.

Register nothing on the repository. The App already delivers, and its events reach the fleets whose repositories name that repository.

A fleet URL

Use this for any provider without a connected App.

Save the fleet, then read its webhook URLs. <FLEET_ID> comes from agentsfleet list.
agentsfleet --json fleet show <FLEET_ID>
<varies>
Copy the url from the webhook_urls entry whose source matches the provider. Each source has its own URL, ending in /v1/webhooks/<FLEET_ID>/<SOURCE>, including Svix senders. The former /v1/webhooks/svix/<FLEET_ID> address returns 404; replace it with the URL Save returns.
Register the URL and signing secret with the provider. For GitHub, open Repository settings → Webhooks → Add webhook. Choose the required event names. The GitHub fleet URL accepts pull request (PR) actions opened, reopened, synchronize, and ready_for_review. A connected App also accepts other PR actions. Both paths ignore repair branches.
Send a provider test event. The provider owns delivery and retries. agentsfleet owns the URL until the fleet is deleted.

Verify it works

<FLEET_ID> comes from agentsfleet list.

agentsfleet events <FLEET_ID> --actor 'webhook:*' --since 1h

<varies>

A successful request returns HTTP 202. A filtered or inactive event returns HTTP 200 without opening a run.

Common problems

Error	Why it happened	Fix
`UZ-WH-001`	The fleet URL is wrong or deleted, or the fleet has no webhook trigger with that source.	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 has no usable signing secret for the trigger.	Store `webhook_secret` in the secret named by `credential_name`, or `source` when omitted. Svix requires its full valid `whsec_` value in that 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. Rate-limited requests include Retry-After. The provider should wait for that delay before retrying.

Remove or undo

Delete the webhook from the provider first. Choose Edit setup in the fleet header, then ask the chat to remove the trigger. Review the updated setup and choose Save changes beside the chat. Deleting the fleet removes its webhook URL. Requests to the old URL then return UZ-WH-001.

Start here

Work with fleets

Connect apps and tools

Memory and context

Workspace and account

Help and updates

What this does

Before you begin

Steps

A connected GitHub App

A fleet URL

Verify it works

Common problems

Remove or undo

​What this does

​Before you begin

​Steps

​A connected GitHub App

​A fleet URL

​Verify it works

​Common problems

​Remove or undo

​Related pages

What this does

Before you begin

Steps

A connected GitHub App

A fleet URL

Verify it works

Common problems

Remove or undo

Related pages