Trigger via Webhooks

Notify your AI employees when something happens in your system. Fire-and-forget: you get 202 Accepted immediately, the employee processes the event in the background using their skills and tools.

TL;DR

POST an event to /api/webhook/ with your API key, an employee ID, and a payload describing what happened. The employee picks it up and acts on it. No waiting for a response.

This page covers inbound webhooks (external systems trigger your employee). For outbound webhooks (your employee sends data to external systems), see Send Outbound Webhooks in the Tools and Capabilities section.

When to Use This

Use webhooks when you want to tell an employee that something happened but do not need an immediate answer. The employee receives the event, understands the context, and takes action on its own.

• CI/CD. Notify when builds fail, deploys complete, or tests break
• E-commerce. Alert on new orders, refund requests, or inventory changes
• Support. Forward new tickets, escalations, or customer feedback
• Monitoring. Send alerts from Datadog, PagerDuty, or custom health checks
• CRM. Trigger follow-ups when deals close, contacts update, or meetings are scheduled

Webhook vs API: The API waits for a response (request-response). Webhooks are fire-and-forget, meaning you send the event and move on. The employee processes it in the background.

How It Works

Unlike the REST API (which waits for a response), webhooks are asynchronous. You fire an event and move on. The employee receives it, understands the context, and takes action, the same way they would if you told them in chat.

• Fire-and-forget. You get 202 immediately, the employee processes in the background
• Same execution. Webhook events run through the Dispatcher and execution pipeline, identical to every other channel
• Same billing. Credits are tracked and charged the same way
• Shared keys. API keys work across all programmatic channels

Enable the Channel

The Webhook channel is disabled by default. Enable it before sending events:

1. Go to Settings, Technical, Communications
2. Find Webhook under the Inbound channels
3. Toggle it on

Authentication

Same as all programmatic channels. Bearer token in the Authorization header.

1. Go to Settings, Communications
2. Expand the Programmatic group
3. Expand any channel card (API, MCP, Webhook, etc.)
4. Click "New Key", give it a name, hit Enter
5. Copy the key from the green banner. It will not be shown again

Endpoint

POST /api/webhook/

Send an event to an AI employee.

Request body:

Request headers (optional):

Response (202 Accepted):

What the Employee Sees

The employee receives the event formatted as:

[Webhook: order.completed] Customer John placed order #1234 for $99.

If no event type is provided:

[Webhook] Customer John placed order #1234 for $99.

The employee then acts on it using their skills, duties, tools, and memory, just like any other message.

Error Responses

Rate Limits

• Per-IP (failed auth): 10 attempts per minute
• Per-API-key: 120 requests per minute

Exceeding limits returns 429 Too Many Requests.

Quick Start

curl

curl -X POST https://api-sistava.com/api/webhook/ \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "YOUR_EMPLOYEE_UUID",
    "event": "order.completed",
    "payload": "Customer John placed order #1234 for $99."
  }'

Python

import requests

requests.post(
    "https://api-sistava.com/api/webhook/",
    headers={"Authorization": "Bearer sk-your-key"},
    json={
        "employee_id": "YOUR_EMPLOYEE_UUID",
        "event": "deploy.failed",
        "payload": "Deploy to production failed: timeout on health check."
    },
)
# 202: employee will handle it in the background

JavaScript / Node

await fetch("https://api-sistava.com/api/webhook/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-your-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    employee_id: "YOUR_EMPLOYEE_UUID",
    event: "ticket.created",
    payload: "New support ticket #567: 'Cannot log in after password reset'",
  }),
});
// 202: fire and forget

With Idempotency Key

curl -X POST https://api-sistava.com/api/webhook/ \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234-completed" \
  -d '{
    "employee_id": "YOUR_EMPLOYEE_UUID",
    "event": "order.completed",
    "payload": "Customer John placed order #1234 for $99."
  }'

Sending the same Idempotency-Key within 5 minutes returns 200 {"status": "duplicate"} instead of processing the event again. Use this to safely retry without triggering duplicate work.

Event Type Best Practices

Use dot-notation event types for clarity:

• order.completed
• support.ticket_created
• deploy.failed
• user.signed_up

The event type is prepended to the payload as context for the employee: [Webhook: order.completed] Customer John placed order #1234...

Good to Know

• No response content. Webhooks are fire-and-forget. If you need the employee's answer, use the REST API instead
• Team leaders. If the employee is a team leader, they may delegate the event to a team member
• Idempotency. Use the Idempotency-Key header to prevent duplicate processing during retries. The key is valid for 5 minutes
• Payload size. Request body cannot exceed 64 KB. Keep payloads concise, include only the information the employee needs to act on
• Managing keys. Create, rename, and revoke from the Communications page. Revoking blocks all channels immediately

Troubleshooting

• 401 Unauthorized. Missing or invalid API key. Include Authorization: Bearer sk-... in the request header.
• 403 Forbidden. The webhook channel is not enabled. Enable it in Settings, Technical, Communications.
• 400 Bad Request. Check that employee_id is a valid UUID and payload is a non-empty string. The body must be valid JSON.
• 429 Too Many Requests. You are exceeding rate limits (120 per minute per key). Back off and retry.
• Employee not acting on the event. Make sure the payload text clearly describes what happened and what action is expected. Use the event field for context.

Frequently Asked Questions

Q: Can I get the employee's response from a webhook? A: No. Webhooks are fire-and-forget. The employee processes the event in the background. If you need a response, use the REST API or A2A channel instead.

Q: How do I prevent duplicate events? A: Include an Idempotency-Key header with a unique value per event. If the same key is sent within 5 minutes, the duplicate request is rejected.

Q: What format should the payload be in? A: Plain text describing what happened. Write it the way you would tell a colleague: "New order #1234 from John for $99, requesting express shipping."

Q: Can I send structured JSON in the payload? A: The payload field must be a string. You can JSON-stringify an object and pass it as a string, but plain text usually works better because the employee reads it as a natural language prompt.

Q: Do webhooks cost credits? A: Yes. The employee processes the event the same way it would process any message. Token credits and runtime credits apply.