# Inbound webhooks

`POST /api/webhook/`

POST an event from your systems and an employee picks it up and acts in the background. Fire-and-forget — no response to wait on.

## Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `employee_id` | uuid | yes | The employee that should react to the event. |
| `event` | string | no | Event type, prepended to the payload as context (e.g. order.completed). |
| `payload` | string | yes | Plain text describing what happened and what action is expected. |

## Request headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | yes | Bearer sk-your-api-key |
| `Idempotency-Key` | string | no | Optional. Same key within 5 min returns 200 {"status":"duplicate"} instead of reprocessing. |

## Error responses

| Status | Meaning |
| --- | --- |
| 400 | Bad request — missing fields, invalid UUID, or malformed JSON |
| 401 | Invalid or missing API key |
| 403 | Channel not enabled, or email not verified |
| 413 | Request body exceeds 64 KB |
| 429 | Rate limit exceeded — see Retry-After header |
| 502 | Employee unreachable (infrastructure error) |
| 504 | Employee timed out (5 minute limit) |

## Request - cURL

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

## Request - Python

```
import requests

requests.post(
    "https://sistava.com/api/webhook/",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "employee_id": "YOUR_EMPLOYEE_UUID",
        "event": "deploy.failed",
        "payload": "Deploy to production failed: timeout on health check.",
    },
)
```

## Response 202

```json
{
  "status": "accepted"
}
```

Concepts and walkthrough: https://sistava.com/en/guide/channels/webhooks

API reference index: https://sistava.com/en/docs