Webhooks

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	`"github"`	Repository events: issues, pull requests, pushes, workflow runs, and more
Sentry	`"sentry"`	Error monitoring events: alerts, issues, errors, comments
Linear	`"linear"`	Project management events: issues, comments, labels
Mintlify	`"mintlify"`	Documentation events: build successes and failures
Slack	`"slack"`	Workspace events: messages, app mentions, reactions
Discord	`"discord"`	Discord Interactions Endpoint: slash commands, message components, modals, autocomplete
X (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:

[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:

# 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

The gateway receives a webhook POST request at /webhooks/<type> (e.g. /webhooks/github)
It verifies the payload signature using secrets loaded from the credential instances defined in config.toml webhook sources
It parses the event into a WebhookContext (source, event, action, repo, etc.)
It matches the context against each agent’s webhook triggers
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

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).
Check the webhook secret — if using HMAC validation, the secret in al creds must match the one configured in the external service.
Check event filters — verify the events, actions, and other filter fields in the agent’s config.toml match the incoming event.

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:

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

In the Discord Developer Portal, create or select your application
Under General Information, copy your Application ID and Public Key
Under Bot, copy or reset your Bot Token
Add these to your credentials: al creds add discord_bot
Set your Interactions Endpoint URL to https://your-server:8080/webhooks/discord
Discord will send a PING verification request — Action Llama responds automatically after validating the signature

Example Configuration

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

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

First Steps

Guides

Concepts

Integrations

Reference

Supported Providers

Defining Webhook Sources

Agent Webhook Triggers

How Webhooks Work at Runtime

Hybrid Agents

Troubleshooting

Webhooks not firing

Webhook events being dropped

Discord Webhooks

Setup

Example Configuration

​Supported Providers

​Defining Webhook Sources

​Agent Webhook Triggers

​How Webhooks Work at Runtime

​Hybrid Agents

​Troubleshooting

​Webhooks not firing

​Webhook events being dropped

​Discord Webhooks

​Setup

​Example Configuration

Supported Providers

Defining Webhook Sources

Agent Webhook Triggers

How Webhooks Work at Runtime

Hybrid Agents

Troubleshooting

Webhooks not firing

Webhook events being dropped

Discord Webhooks

Setup

Example Configuration