Webhook Triggers

Trigger agent executions via HTTP webhooks with token authentication, HMAC signing, input mapping, and rate limiting.

Webhook Triggers

Webhook triggers allow external systems to execute agents via HTTP requests. Each trigger is bound to a specific agent and authenticated with a unique token. Webhook triggers enable integrations with CI/CD pipelines, monitoring systems, form submissions, and any system that can make HTTP requests.

What Are Webhook Triggers?

A webhook trigger is a URL endpoint that, when called, executes a specific agent. Triggers include:

• Token authentication -- Each trigger has a unique, encrypted token
• HMAC secret signing -- Optional request signature verification
• Input mapping -- Map webhook payload fields to agent input parameters
• Rate limiting -- 30 requests per minute per IP address
• Activation control -- Enable or disable triggers without deleting them

Creating Triggers

Python SDK

trigger = client.webhook_triggers.create(
    agent_id="your-agent-id",
    name="GitHub PR Review",
    generate_secret=True  # Generate HMAC signing secret
)
 
print(f"Trigger ID: {trigger['data']['id']}")
print(f"Token: {trigger['data']['token']}")  # Only shown once
print(f"Secret: {trigger['data']['secret']}")  # Only shown once (if generated)

JavaScript SDK

const trigger = await client.webhookTriggers.create({
  agentId: 'your-agent-id',
  name: 'GitHub PR Review',
  generateSecret: true,
})
 
console.log(`Token: ${trigger.data.token}`)
console.log(`Secret: ${trigger.data.secret}`)

The token and secret are only returned at creation time. Store them securely.

Token Authentication

Every webhook request must include the trigger token for authentication. Include it in the Authorization header:

curl -X POST https://api.promptrails.ai/api/v1/webhook/trigger \
  -H "Authorization: Bearer wht_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Review this PR", "pr_number": 42}'

HMAC Secret Signing

When a secret is configured, PromptRails verifies request signatures to ensure requests are authentic:

1. The sender computes an HMAC-SHA256 of the request body using the shared secret
2. The signature is included in the request header
3. PromptRails verifies the signature before processing

import hmac
import hashlib
import json
import requests
 
payload = json.dumps({"message": "Hello"})
signature = hmac.new(
    secret.encode(),
    payload.encode(),
    hashlib.sha256
).hexdigest()
 
response = requests.post(
    "https://api.promptrails.ai/api/v1/webhook/trigger",
    headers={
        "Authorization": "Bearer wht_abc123...",
        "X-Webhook-Signature": f"sha256={signature}",
        "Content-Type": "application/json"
    },
    data=payload
)

Input Mapping

The webhook payload is passed directly as the agent's input. Structure your webhook payload to match the agent's input schema:

# If the agent expects {"message": string, "priority": string}
curl -X POST https://api.promptrails.ai/api/v1/webhook/trigger \
  -H "Authorization: Bearer wht_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Server CPU usage exceeded 90%",
    "priority": "high"
  }'

Rate Limiting

Webhook triggers are rate limited to 30 requests per minute per IP address. Exceeding this limit returns a 429 Too Many Requests response.

If you need higher throughput, consider:

• Batching requests
• Using the standard API with an API key instead
• Distributing requests across multiple source IPs

Activate / Deactivate

Temporarily disable a trigger without deleting it:

# Deactivate
client.webhook_triggers.update(
    trigger_id="trigger-id",
    is_active=False
)
 
# Reactivate
client.webhook_triggers.update(
    trigger_id="trigger-id",
    is_active=True
)

Requests to inactive triggers return a 403 Forbidden response.

Managing Triggers

List Triggers

triggers = client.webhook_triggers.list()
 
for trigger in triggers["data"]:
    status = "active" if trigger["is_active"] else "inactive"
    print(f"{trigger['name']} ({status}) - Agent: {trigger['agent_id']}")
    print(f"  Token prefix: {trigger['token_prefix']}...")
    print(f"  Has secret: {trigger['has_secret']}")
    print(f"  Last used: {trigger.get('last_used_at', 'Never')}")

Delete a Trigger

client.webhook_triggers.delete(trigger_id="trigger-id")

Trigger Response Fields

Use Cases

• CI/CD Integration -- Trigger code review agents on pull requests
• Monitoring Alerts -- Execute diagnostic agents when alerts fire
• Form Submissions -- Process form data through AI agents
• Scheduled Tasks -- Use cron jobs to trigger periodic agent executions
• Third-Party Webhooks -- Connect Slack, GitHub, Jira, or any webhook-capable system

Related Topics

• Agents -- The agents that webhook triggers execute
• API Keys and Scopes -- Alternative authentication method
• Executions -- Webhook-triggered executions