Triggers
Fire an action whenever a matching record is written to an agent.
What you'll learn
- ✓POST /v1/agents/:id/triggers — name, on_write, filter, action
- ✓action types: write to another agent, call a webhook
- ✓Filter applies before trigger fires — only matching records trigger
- ✓GET /v1/agents/:id/triggers — list
- ✓Use case: payment → notification, signup → onboarding event
Trigger on users when plan='enterprise'. Write a regular user, then an enterprise user. Confirm enterprise_alerts received a record only for the enterprise user.
What you'll learn
Fire a webhook whenever a record is written to a specific agent — event-driven automation within SapixDB.
How triggers work
A trigger watches one agent (watch_agent_id) for writes. When a new record arrives on that agent, SapixDB sends an HTTP POST to the configured webhook_url with the record payload. Triggers are agent-global — they fire on every write to the watched agent.
Create a trigger
curl -s -X POST http://localhost:7475/v1/triggers \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{
"name": "order-webhook",
"watch_agent_id": "orders",
"event_type": "record.written",
"webhook_url": "https://your-service.com/webhooks/order-paid"
}' | python3 -m json.toolNow every time a record is written to the orders agent, SapixDB POSTs the event to your webhook URL.
List triggers
curl -s http://localhost:7475/v1/triggers \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
| python3 -m json.toolTrigger request fields
| Field | Required | Description |
|---|---|---|
name | Yes | Human-readable label |
watch_agent_id | Yes | Agent to watch for writes |
event_type | No | Defaults to record.written |
webhook_url | Yes | HTTP endpoint to notify |
webhook_secret | No | Passed as X-Sapix-Secret header for verification |
enabled | No | Defaults to true |
Challenge
Create a trigger that watches the users agent. Write a user record. Inspect the webhook delivery (use a service like webhook.site to capture the request). Confirm the payload contains the record.
---