Skip to content

Webhooks

Webhooks let you trigger agent teams from external systems via HTTP. Define a prompt template with variables, secure it with a token, and call the endpoint from CI/CD pipelines, monitoring alerts, third-party integrations, or any system that can make HTTP requests.

Use Cases

  • CI/CD: Trigger a code review team when a pull request is opened, or run a deployment checklist after a merge.
  • Alerts: Route monitoring alerts (PagerDuty, Grafana, Datadog) to an SRE agent team for automated triage.
  • Third-party integrations: Connect CRM events, form submissions, or Slack slash commands to specialized agent teams.
  • Scheduled external triggers: Use external schedulers (GitHub Actions cron, AWS EventBridge) to trigger agent workflows with dynamic context.

How Webhooks Work

When a webhook is triggered, AgentCrew performs the following steps:

  1. Authenticate the incoming request by verifying the token in the URL.
  2. Render the prompt template by replacing {{variables}} with values from the request body.
  3. Send the rendered prompt to the team leader via NATS.
  4. Respond immediately (fire-and-forget) or wait for the agent's response (wait-for-response mode).
  5. Record the execution in the webhook's run history.

Unlike schedules, webhooks do not deploy or tear down teams. The target team must already be running when the webhook is triggered. This design keeps webhook responses fast and avoids container startup latency.

Creating a Webhook

Navigate to the Webhooks section in the sidebar and click New Webhook. The webhook builder walks you through:

  1. Name: A descriptive name for the webhook (e.g., "PR Review Trigger", "Alert Triage").
  2. Team: Select which agent team will receive the prompt. The team must already exist.
  3. Prompt Template: The instruction sent to the team leader when the webhook fires. Use {{variable_name}} placeholders for dynamic values that will be replaced at trigger time.
  4. Timeout: Maximum time to wait for a response when using wait-for-response mode. Defaults to the global WEBHOOK_TIMEOUT setting.
  5. Max Concurrent: Maximum number of simultaneous executions for this webhook. Additional triggers are queued.

After creation, a unique token is generated and displayed once. Copy and store it securely — it cannot be retrieved again.

Triggering a Webhook

Send a POST request to the trigger endpoint with the webhook token: 

POST /webhook/trigger/:token

The request body must be JSON with a variables object containing the key-value pairs that match your prompt template placeholders: 

{
  "variables": {
    "pr_title": "Add user authentication",
    "pr_url": "https://github.com/org/repo/pull/42",
    "author": "alice"
  }
}

Fire-and-Forget Mode (Default)

By default, the webhook returns immediately with a 202 Accepted response, confirming the prompt was queued for processing: 

curl -X POST https://your-agentcrew/webhook/trigger/whk_abc123def456 \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "alert_name": "High CPU Usage",
      "service": "api-server",
      "severity": "warning"
    }
  }'

# Response: 202 Accepted
# {  "status": "accepted", "run_id": "..." }

Wait-for-Response Mode

Add ?wait=true to the trigger URL to wait for the agent team's response. The request blocks until the agent responds or the timeout is reached: 

curl -X POST "https://your-agentcrew/webhook/trigger/whk_abc123def456?wait=true" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "pr_title": "Add user authentication",
      "pr_url": "https://github.com/org/repo/pull/42"
    }
  }'

# Response: 200 OK (with agent response)
# {  "status": "success", "response": "...", "run_id": "..." }

# Or: 408 Request Timeout (if timeout is reached)
# {  "status": "timeout", "run_id": "..." }

Token Security

  • Tokens use the whk_ prefix for easy identification in logs and configuration.
  • Tokens are SHA-256 hashed before storage — the plaintext token is never persisted in the database.
  • The plaintext token is shown only once at creation time. If lost, you must regenerate a new token.

Managing Webhooks

Regenerating Tokens

If a token is compromised or lost, you can regenerate it from the webhook detail page. The old token is immediately invalidated and a new one is displayed once.

Run History

Each webhook maintains a paginated history of all executions. For every run you can see:

  • Status: success, error, or timeout.
  • Started at / Finished at: Timestamps in your local timezone.
  • Duration: How long the execution took.
  • Variables: The variables sent in the trigger request.
  • Conversation: Expand any run to see the rendered prompt and the agent's response.

Enable / Disable

Each webhook has a toggle to enable or disable it. Disabled webhooks return 404 Not Found when triggered, preventing accidental executions.

Editing

Click any webhook to edit its name, prompt template, team, timeout, or max concurrent setting. Changes take effect immediately for subsequent triggers.

Deleting

Deleting a webhook removes it and all its run history permanently. The token is immediately invalidated.

Configuration

Webhook behavior can be tuned with environment variables:

Variable Default Description
WEBHOOK_MAX_CONCURRENT 20 Global maximum number of webhook executions that can run simultaneously. Excess triggers are queued. Can also be overridden per-webhook.

Architecture Notes

  • The webhook engine runs as part of the API server process — no separate service is needed.
  • Webhooks require the target team to be already running. Unlike schedules, they do not deploy or tear down teams.
  • Per-team FIFO processing: When multiple webhooks (or webhooks and chat messages) target the same team, messages are queued and processed one at a time in arrival order. A correlation ID ensures each caller receives the correct response, using the same NATS FIFO correlation mechanism as schedules.
  • Concurrency is controlled at two levels: the global WEBHOOK_MAX_CONCURRENT setting and the per-webhook max_concurrent setting.

Next Steps

  • Schedules: Automate recurring tasks with cron-based schedules that deploy and tear down teams automatically.
  • Configuration: Review all environment variables including webhook-specific settings.
  • Architecture: Understand how webhooks fit into the overall system design.