Skip to main content
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

ProviderTypeDescription
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)
FieldTypeRequiredDescription
typestringYesProvider type: "github", "sentry", "linear", "mintlify", "slack", "discord", or "twitter"
credentialstringNoCredential 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

  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.
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 FieldTypeDescription
eventsstring[]Interaction types: application_command, message_component, modal_submit, autocomplete
guildsstring[]Discord guild (server) IDs to filter on
channelsstring[]Channel IDs to filter on
commandsstring[]Slash command names (e.g. ask, deploy) — only applies to application_command and autocomplete events

​
Setup

  1. In the Discord Developer Portal, 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

# 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"]