Webhook Triggers

Webhook triggers let you start agents by sending an HTTP request. This is perfect for integrating with external services, automation tools, or custom applications.

What Are Webhooks?

A webhook is a URL that, when called, triggers your agent to run. Any service that can make HTTP requests can trigger your agent.

Setting Up a Webhook Trigger

https://billix.io/api/agents/webhook/abc123xyz

Webhook URL Format

Your webhook URL looks like:

https://billix.io/api/agents/webhook/{agent-id}

Keep this URL secure—anyone with it can trigger your agent.

Making Webhook Requests

Basic Request

curl -X POST https://billix.io/api/agents/webhook/abc123xyz

With Payload Data

Send data to your agent:

curl -X POST https://billix.io/api/agents/webhook/abc123xyz \
  -H "Content-Type: application/json" \
  -d '{"customer_name": "John", "order_id": "12345"}'

Your agent can access this data in its instructions using {{payload.customer_name}}.

With Authentication

If you've set up API key authentication:

curl -X POST https://billix.io/api/agents/webhook/abc123xyz \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

Authentication Options

No Authentication

Any request triggers the agent. Use for testing or trusted environments only.

API Key

Require a specific API key in the Authorization header:

Header: Authorization: Bearer your-secret-key

Webhook Secret

Verify requests using a shared secret signature:

Header: X-Webhook-Signature: sha256=abc123...

Billix validates the signature matches the payload.

Using Payload Data

Data sent to the webhook is available in your agent's instructions:

Accessing Payload Variables

Agent Instructions:

Process the new order:
- Customer: {{payload.customer_name}}
- Order ID: {{payload.order_id}}
- Amount: {{payload.amount}}

Create a confirmation and send it to the customer.

Example Payload

{
  "customer_name": "Jane Smith",
  "order_id": "ORD-98765",
  "amount": 150.00,
  "items": ["Product A", "Product B"]
}

Integration Examples

Zapier

1. Create a Zapier Zap
2. Add an action: "Webhooks by Zapier"
3. Choose "POST"
4. Enter your Billix webhook URL
5. Configure payload with data from your trigger

GitHub

1. Go to repo Settings → Webhooks
2. Add webhook with your Billix URL
3. Select events to trigger (push, PR, etc.)
4. GitHub will call your agent on those events

Stripe

1. Go to Developers → Webhooks in Stripe
2. Add endpoint with your Billix URL
3. Select events (payment succeeded, etc.)
4. Stripe will notify your agent

Slack

1. Create a Slack app
2. Enable Event Subscriptions
3. Set Request URL to your Billix webhook
4. Subscribe to events you want to handle

Make (Integromat)

1. Create a scenario
2. Add HTTP module
3. Configure POST request to your webhook URL
4. Map data from previous modules

Testing Webhooks

Using the Billix UI

1. Go to your agent's detail page
2. Click "Test Webhook"
3. Optionally enter test payload
4. See the execution result

Using cURL

curl -X POST https://billix.io/api/agents/webhook/abc123xyz \
  -H "Content-Type: application/json" \
  -d '{"test": true, "message": "Hello from cURL"}'

Using Postman

1. Create new POST request
2. Enter your webhook URL
3. Set Body to raw JSON
4. Add your test payload
5. Send and check response

Webhook Response

When your webhook is called, Billix returns:

Success (200)

{
  "status": "triggered",
  "execution_id": "exec_abc123",
  "agent_id": "agent_xyz789"
}

Error (4xx/5xx)

{
  "error": "Invalid authentication",
  "code": "AUTH_FAILED"
}

Common Patterns

Process External Events

When webhook is called:
1. Parse the incoming {{payload}}
2. Determine event type from {{payload.event}}
3. Take appropriate action based on event
4. Log the result

Data Sync

When webhook receives new data:
1. Extract records from {{payload.records}}
2. For each record, check if it exists in Notion
3. If new, create; if exists, update
4. Send summary to Slack

Alert and Notify

When webhook signals an alert:
1. Read alert details from {{payload}}
2. Determine severity from {{payload.level}}
3. If critical, send immediate Slack message to #alerts
4. Log all alerts to a Google Sheet

Security Best Practices

1. Always use authentication for production webhooks
2. Restrict IP addresses if you know the source
3. Validate payload before processing
4. Rotate secrets periodically
5. Monitor webhook activity for unusual patterns
6. Don't expose sensitive data in webhook URLs

Common Questions

Next Steps

• Learn about event triggers
• Review agent best practices
• Set up monitoring