# Webhook Triggers

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

Source: https://0.0.0.0:8080/docs/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**

```python
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**

```typescript
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:

```bash
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

```python
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:

```bash
# 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:

```python
# 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

```python
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

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

## Trigger Response Fields

| Field           | Type      | Description                        |
| --------------- | --------- | ---------------------------------- |
| `id`            | KSUID     | Unique trigger identifier          |
| `workspace_id`  | KSUID     | Workspace scope                    |
| `agent_id`      | KSUID     | Bound agent ID                     |
| `name`          | string    | Display name                       |
| `token_prefix`  | string    | First characters of the token      |
| `is_active`     | boolean   | Whether the trigger is active      |
| `has_secret`    | boolean   | Whether HMAC signing is configured |
| `last_used_at`  | timestamp | Last invocation time               |
| `created_by_id` | KSUID     | Creator user ID                    |
| `created_at`    | timestamp | Creation time                      |
| `updated_at`    | timestamp | Last update time                   |

## 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](/docs/agents) -- The agents that webhook triggers execute
- [API Keys and Scopes](/docs/api-keys-and-scopes) -- Alternative authentication method
- [Executions](/docs/executions) -- Webhook-triggered executions