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

# Webhooks

> Webhook setup, providers, filter fields, and troubleshooting

Action Llama agents can be triggered by webhooks in addition to (or instead of) cron schedules. Seven providers are supported: GitHub, Sentry, Linear, Mintlify, Slack, Discord, and X (Twitter).

## Supported Providers

| Provider                                   | Type         | Description                                                                             |
| ------------------------------------------ | ------------ | --------------------------------------------------------------------------------------- |
| [GitHub](/reference/webhooks/github)       | `"github"`   | Repository events: issues, pull requests, pushes, workflow runs, and more               |
| [Sentry](/reference/webhooks/sentry)       | `"sentry"`   | Error monitoring events: alerts, issues, errors, comments                               |
| [Linear](/reference/webhooks/linear)       | `"linear"`   | Project management events: issues, comments, labels                                     |
| [Mintlify](/reference/webhooks/mintlify)   | `"mintlify"` | Documentation events: build successes and failures                                      |
| [Slack](/reference/webhooks/slack)         | `"slack"`    | Workspace events: messages, app mentions, reactions                                     |
| [Discord](/reference/webhooks/discord)     | `"discord"`  | Discord Interactions Endpoint: slash commands, message components, modals, autocomplete |
| [X (Twitter)](/reference/webhooks/twitter) | `"twitter"`  | Account activity events: tweets, likes, follows, direct messages                        |

See each provider's page for filter fields, setup instructions, and example configurations.

## Defining Webhook Sources

Webhook sources are defined once in the project's `config.toml`. Each source has a name, a provider type, and an optional credential for signature validation:

```toml theme={null}
[webhooks.my-github]
type = "github"
credential = "MyOrg"          # credential instance name (github_webhook_secret:MyOrg)

[webhooks.my-sentry]
type = "sentry"
credential = "SentryProd"     # credential instance name (sentry_client_secret:SentryProd)

[webhooks.my-linear]
type = "linear"
credential = "LinearMain"     # credential instance name (linear_webhook_secret:LinearMain)

[webhooks.my-mintlify]
type = "mintlify"
credential = "MintlifyMain"   # credential instance name (mintlify_webhook_secret:MintlifyMain)

[webhooks.my-slack]
type = "slack"
credential = "MainWorkspace"  # credential instance name (slack_signing_secret:MainWorkspace)

[webhooks.my-twitter]
type = "twitter"
credential = "MyXApp"         # credential instance name (x_twitter_api:MyXApp)
```

| Field        | Type   | Required | Description                                                                                             |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `type`       | string | Yes      | Provider type: `"github"`, `"sentry"`, `"linear"`, `"mintlify"`, `"slack"`, `"discord"`, or `"twitter"` |
| `credential` | string | No       | Credential instance name for HMAC signature validation. Omit for unsigned webhooks.                     |

## Agent Webhook Triggers

Agents reference a webhook source by name and add filters in their `config.toml`:

```toml theme={null}
# agents/<name>/config.toml
[[webhooks]]
source = "my-github"
repos = ["acme/app"]
events = ["issues"]
actions = ["labeled"]
labels = ["agent"]
```

Each `[[webhooks]]` entry is a trigger. The `source` field (referencing a name from the project's `config.toml`) is required. All filter fields are optional — omit all of them to trigger on everything from that source.

An agent must have at least one of `schedule` or `webhooks` (or both).

## How Webhooks Work at Runtime

1. The gateway receives a webhook POST request at `/webhooks/<type>` (e.g. `/webhooks/github`)
2. It verifies the payload signature using secrets loaded from the credential instances defined in `config.toml` webhook sources
3. It parses the event into a `WebhookContext` (source, event, action, repo, etc.)
4. It matches the context against each agent's webhook triggers
5. Matching agents are triggered with the webhook context injected into their prompt

## Hybrid Agents

Agents can have both `schedule` and `webhooks`. Scheduled runs poll for work proactively; webhook runs respond to events immediately.

## Troubleshooting

### Webhooks not firing

1. **Check the webhook URL** — GitHub/Sentry/Linear must be able to reach your gateway. For local development, use a tunnel (e.g. ngrok, Cloudflare Tunnel).
2. **Check the webhook secret** — if using HMAC validation, the secret in `al creds` must match the one configured in the external service.
3. **Check event filters** — verify the `events`, `actions`, and other filter fields in the agent's `config.toml` match the incoming event.

```bash theme={null}
al doctor    # Validates webhook trigger field names and types
```

### Webhook events being dropped

If runners are busy, events are queued (up to `workQueueSize`, default 100). If the queue is full, old events are dropped. Check queue depth with `al stat`.

To handle more concurrent events, increase `scale` in the agent's `config.toml`:

```toml theme={null}
scale = 3    # Run up to 3 instances concurrently
```

## Discord Webhooks

Discord support uses the **Interactions Endpoint** (HTTP-based), which covers slash commands, message components, modals, and autocomplete. This requires a `discord_bot` credential with your application's public key for Ed25519 signature verification.

| Filter Field | Type      | Description                                                                                                  |
| ------------ | --------- | ------------------------------------------------------------------------------------------------------------ |
| `events`     | string\[] | Interaction types: `application_command`, `message_component`, `modal_submit`, `autocomplete`                |
| `guilds`     | string\[] | Discord guild (server) IDs to filter on                                                                      |
| `channels`   | string\[] | Channel IDs to filter on                                                                                     |
| `commands`   | string\[] | Slash command names (e.g. `ask`, `deploy`) — only applies to `application_command` and `autocomplete` events |

### Setup

1. In the [Discord Developer Portal](https://discord.com/developers/applications), create or select your application
2. Under **General Information**, copy your **Application ID** and **Public Key**
3. Under **Bot**, copy or reset your **Bot Token**
4. Add these to your credentials: `al creds add discord_bot`
5. Set your Interactions Endpoint URL to `https://your-server:8080/webhooks/discord`
6. Discord will send a PING verification request — Action Llama responds automatically after validating the signature

### Example Configuration

```toml theme={null}
# In project config.toml
[webhooks.my-discord]
type = "discord"
credential = "MyBot"     # discord_bot credential instance name
```

```toml theme={null}
# In agents/<name>/config.toml
[[webhooks]]
source = "my-discord"
events = ["application_command"]
commands = ["ask", "status"]
guilds = ["1234567890"]
```