> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentsfleet.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure a webhook

> Send signed provider events to a fleet.

# Configure a webhook

## What this does

A webhook sends provider events to one fleet. `agentsfleet` verifies the request before creating an event.

GitHub App events can use managed ingress. Other providers can use the fleet URL printed during installation.

## Before you begin

Create a workspace secret that contains the provider's signing secret. Add a webhook trigger to `TRIGGER.md`.

```yaml theme={"theme":"vesper"}
x-agentsfleet:
  triggers:
    - type: webhook
      source: github
      events:
        - pull_request
      credential_name: github
```

## Steps

1. Install or update the fleet.

   ```bash theme={"theme":"vesper"}
   agentsfleet install --library github-pr-reviewer
   ```

   ```text theme={"theme":"vesper"}
   ✓ github-pr-reviewer is live.
     Fleet ID: <varies>
     Webhook URLs (register on the upstream provider):
       github: <varies>
   ```

2. Copy the URL printed for the matching source.

3. Register the URL and signing secret with the provider.

   For GitHub, open **Repository settings → Webhooks → Add webhook**. Choose the required event names.

4. 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 the install output.

```bash theme={"theme":"vesper"}
agentsfleet events <FLEET_ID> --actor 'webhook:*' --since 1h
```

```text theme={"theme":"vesper"}
<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.                   | 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-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. Then remove its trigger from `TRIGGER.md` and update the fleet.

Deleting the fleet removes its webhook URL. Requests to the old URL then return `UZ-WH-001`.

## Related pages

* [Author a fleet](/fleets/authoring)
* [Secrets](/fleets/secrets)
* [Troubleshooting](/fleets/troubleshooting)