Overview
Trix webhooks allow you to receive HTTP callbacks when events occur in your account. This enables:
- Real-time integrations - Get notified instantly when memories, clusters, or spaces change
- Automated workflows - Trigger actions in external systems based on Trix events
- Data synchronization - Keep external databases in sync with your memory store
- Custom dashboards - Build real-time monitoring and analytics
Quick Start
1. Create a Webhook
Terminal
curl -X POST https://api.trixdb.com/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My Integration",
"url": "https://your-server.com/webhooks/trix",
"events": ["memory.created", "memory.updated"]
}'2. Receive Events
Trix will POST events to your URL:
Webhook Payload
{
"id": "evt_abc123",
"event": "memory.created",
"created_at": "2024-01-15T10:30:00Z",
"account_id": "acc_xyz",
"data": {
"id": "mem_123",
"content": "User prefers dark mode",
"space": "default"
}
}3. Verify & Respond
server.ts
app.post('/webhooks/trix', (req, res) => {
// Verify signature (see Security section)
const signature = req.headers['x-webhook-signature'];
// Process event
const event = req.body;
console.log(`Received ${event.event}: ${event.data.id}`);
// Always respond quickly with 200
res.status(200).send('OK');
});Use the Test Webhook feature to verify your endpoint before going live. This sends a test event without affecting your data.
Common Use Cases
| Use Case | Events to Subscribe | Description |
|---|---|---|
| Backup to external DB | memory.created, memory.updated, memory.deleted | Mirror memories to PostgreSQL, MongoDB, or data warehouse |
| Slack notifications | memory.created | Post to Slack when important memories are stored |
| Analytics pipeline | memory.created, memory.accessed | Track usage patterns and memory access |
| Workflow automation | cluster.memory_added | Trigger workflows when memories are organized |
| ML pipeline | audio.transcribed | Process transcriptions with custom ML models |
| Audit logging | All events (*) | Maintain comprehensive audit trail |
Event Categories
Subscribe to events across these categories:
| Category | Events | Description |
|---|---|---|
| Memory | created, updated, deleted, accessed | Core memory lifecycle events |
| Cluster | created, updated, deleted, memory_added, memory_removed | Memory organization events |
| Space | created, updated, deleted | Workspace management events |
| Relationship | created, updated, deleted | Knowledge graph connection events |
| Audio | uploaded, transcribed | Audio processing events |
| ML Workers | clustering:completed, patterns:discovered, anomalies:detected | Background processing results |
See the Event Types page for complete event documentation with payload examples.
Key Features
- Space-scoped webhooks - Optionally filter events to a specific space
- Custom headers - Add authentication headers for your endpoint
- Event filtering - Use filters to narrow down which events trigger delivery
- Automatic retries - Failed deliveries are retried with exponential backoff
- Delivery history - View complete history of all webhook deliveries
- Manual retry - Retry failed deliveries on demand
- Test mode - Send test events to verify your endpoint
- Signature verification - HMAC-SHA256 signatures for security
- Bulk operations - Create or delete multiple webhooks at once
Security
Trix implements multiple security measures for webhook delivery:
- HMAC-SHA256 signatures - Every request includes a cryptographic signature
- Timestamp validation - Prevent replay attacks with 5-minute freshness window
- Secret rotation - Update webhook secrets without downtime
- HTTPS required - Webhooks are only delivered to secure endpoints
Signature Headers
| Header | Description |
|---|---|
X-Webhook-Signature | HMAC-SHA256 signature of timestamp + payload |
X-Webhook-Timestamp | Unix timestamp of when the event was sent |
X-Webhook-Delivery-ID | Unique ID for this delivery (for deduplication) |
X-Webhook-Event | The event type (e.g., memory.created) |
Always verify webhook signatures before processing events. See the Configuration Guide for verification examples.
Reliability
Retry Policy
If your endpoint returns a non-2xx status or times out, Trix retries:
- Max retries: Configurable (1-10, default 3)
- Retry delay: Configurable (10s-3600s, default 60s)
- Timeout: 30 seconds per request
Delivery Status
| Status | Description |
|---|---|
pending | Queued for delivery |
success | Delivered successfully (2xx response) |
retrying | Failed, scheduled for retry |
failed | All retries exhausted |
Webhooks vs Email
Trix offers both webhook and email integration. Choose based on your use case:
| Feature | Webhooks | |
|---|---|---|
| Direction | Outbound only | Inbound + Outbound |
| Use case | Machine-to-machine integration | Human interaction |
| Latency | Real-time (seconds) | Near real-time (minutes) |
| Format | Structured JSON | Natural language |
| Setup | Requires server endpoint | No setup needed |
Documentation
- Event Types - Complete event documentation with payloads
- Webhooks API - REST API reference for webhook management
- Configuration Guide - Setup, verification, and best practices