Webhooks API Reference

Complete REST API documentation for Trix webhook management.

Updated Oct 6, 2026

Overview

Base URL: https://api.trixdb.com/v1

Authentication: All endpoints require a valid API key via the Authorization header.

Header

Authorization: Bearer YOUR_API_KEY

Webhook Endpoints

List Webhooks

Endpoint

GET /webhooks

Parameter	Type	Default	Description
`limit`	integer	20	Results per page (1-100)
`offset`	integer	0	Pagination offset
`event`	string	-	Filter by subscribed event type
`is_active`	boolean	-	Filter by active status
`space_id`	uuid	-	Filter by space

Request

curl -X GET "https://api.trixdb.com/v1/webhooks?limit=10&is_active=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Integration",
      "url": "https://example.com/webhook",
      "events": ["memory.created", "memory.updated"],
      "is_active": true,
      "space_id": null,
      "total_deliveries": 150,
      "successful_deliveries": 148,
      "failed_deliveries": 2,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10,
    "offset": 0,
    "has_more": false
  }
}

Create Webhook

Endpoint

POST /webhooks

Field	Type	Required	Description
`name`	string	Yes	Webhook name (1-255 chars)
`url`	string	Yes	Endpoint URL (must be HTTPS)
`events`	string[]	Yes	Event types to subscribe to
`description`	string	No	Webhook description
`secret`	string	No	Signing secret (auto-generated if not provided)
`space_id`	uuid	No	Limit events to specific space
`headers`	object	No	Custom headers to include
`filters`	object	No	Event payload filters
`max_retries`	integer	No	Max retry attempts (0-10, default 3)
`retry_delay_seconds`	integer	No	Delay between retries (10-3600, default 60)
`is_active`	boolean	No	Enable/disable webhook (default true)

Request

curl -X POST https://api.trixdb.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Notifications",
    "url": "https://hooks.slack.com/services/xxx",
    "events": ["memory.created"],
    "description": "Notify Slack when memories are created",
    "headers": {
      "X-Custom-Header": "my-value"
    },
    "max_retries": 5,
    "retry_delay_seconds": 120
  }'

Response 201

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Slack Notifications",
  "url": "https://hooks.slack.com/services/xxx",
  "events": ["memory.created"],
  "description": "Notify Slack when memories are created",
  "secret": "<32 random bytes, base64url - shown only on create>",
  "space_id": null,
  "headers": {"X-Custom-Header": "my-value"},
  "filters": {},
  "max_retries": 5,
  "retry_delay_seconds": 120,
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z"
}

The secret is only returned in full on creation. Store it securely - you won't be able to retrieve it later.

Get Webhook

Endpoint

GET /webhooks/:webhookId

Request

curl -X GET https://api.trixdb.com/v1/webhooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Webhook

Endpoint

PATCH /webhooks/:webhookId

Request

curl -X PATCH https://api.trixdb.com/v1/webhooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["memory.created", "memory.deleted"],
    "is_active": false
  }'

Delete Webhook

Endpoint

DELETE /webhooks/:webhookId

Request

curl -X DELETE https://api.trixdb.com/v1/webhooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Test Webhook

Send a test event to verify your endpoint is working correctly.

Endpoint

POST /webhooks/:webhookId/test

Request

curl -X POST https://api.trixdb.com/v1/webhooks/550e8400-e29b-41d4-a716-446655440000/test \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "response_status": 200,
  "response_body": "OK",
  "error": null,
  "payload": {
    "id": "evt_test_123",
    "event": "webhook.test",
    "created_at": "2024-01-15T10:30:00Z",
    "data": {
      "webhook_id": "550e8400-e29b-41d4-a716-446655440000",
      "message": "This is a test event",
      "test": true
    }
  },
  "headers_sent": {
    "X-Webhook-ID": "550e8400-e29b-41d4-a716-446655440000",
    "X-Webhook-Event": "webhook.test",
    "X-Webhook-Signature": "t=1705315800,v1=<hex-hmac-sha256>",
    "X-Webhook-Timestamp": "1705315800",
    "X-Webhook-Delivery-ID": "<delivery-uuid>"
  }
}

Delivery Endpoints

List Deliveries

View delivery history for a webhook.

Endpoint

GET /webhooks/:webhookId/deliveries

Parameter	Type	Default	Description
`limit`	integer	20	Results per page (1-100)
`offset`	integer	0	Pagination offset
`status`	string	-	Filter by status: pending, success, failed, retrying
`event_type`	string	-	Filter by event type
`since`	datetime	-	Deliveries after this time
`until`	datetime	-	Deliveries before this time

Request

curl -X GET "https://api.trixdb.com/v1/webhooks/whk_123/deliveries?status=failed&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": "del_456",
      "webhook_id": "whk_123",
      "event_type": "memory.created",
      "status": "failed",
      "attempt_count": 4,
      "payload": { ... },
      "response_status": 500,
      "response_body": "Internal Server Error",
      "error_message": "Connection timeout",
      "created_at": "2024-01-15T10:30:00Z",
      "delivered_at": null
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10,
    "offset": 0,
    "has_more": false
  }
}

Retry Delivery

Manually retry a failed delivery.

Endpoint

POST /webhooks/:webhookId/deliveries/:deliveryId/retry

Request

curl -X POST https://api.trixdb.com/v1/webhooks/whk_123/deliveries/del_456/retry \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "response_status": 200,
  "error": null
}

You cannot retry successful deliveries. Only failed or retrying deliveries can be manually retried.

Statistics

Get Webhook Stats

Get aggregate statistics for all your webhooks.

Endpoint

GET /webhooks/stats

Request

curl -X GET https://api.trixdb.com/v1/webhooks/stats \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "total_webhooks": 5,
  "active_webhooks": 4,
  "inactive_webhooks": 1,
  "total_deliveries": 1250,
  "successful_deliveries": 1230,
  "failed_deliveries": 20,
  "events_distribution": [
    { "event": "memory.created", "webhook_count": 4 },
    { "event": "memory.updated", "webhook_count": 3 },
    { "event": "cluster.memory_added", "webhook_count": 2 }
  ]
}

Event Types

List Available Events

Get all available event types you can subscribe to.

Endpoint

GET /webhooks/event-types

Request

curl -X GET https://api.trixdb.com/v1/webhooks/event-types \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "event_types": [
    "memory.created",
    "memory.updated",
    "memory.deleted",
    "memory.accessed",
    "relationship.created",
    "relationship.updated",
    "relationship.deleted",
    "cluster.created",
    "cluster.updated",
    "cluster.deleted",
    "cluster.memory_added",
    "cluster.memory_removed",
    "space.created",
    "space.updated",
    "space.deleted",
    "feedback.submitted",
    "audio.uploaded",
    "audio.transcribed",
    "webhook.test"
  ],
  "details": [
    {
      "type": "memory.created",
      "description": "Triggered when a new memory is created"
    },
    ...
  ]
}

Bulk Operations

Bulk Create

Create multiple webhooks in a single request.

Endpoint

POST /webhooks/bulk

Request

curl -X POST https://api.trixdb.com/v1/webhooks/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [
      {
        "name": "Webhook 1",
        "url": "https://example.com/webhook1",
        "events": ["memory.created"]
      },
      {
        "name": "Webhook 2",
        "url": "https://example.com/webhook2",
        "events": ["memory.deleted"]
      }
    ]
  }'

Response 201

{
  "created": 2,
  "webhooks": [ ... ]
}

Bulk Delete

Delete multiple webhooks in a single request.

Endpoint

POST /webhooks/bulk/delete

Request

curl -X POST https://api.trixdb.com/v1/webhooks/bulk/delete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "550e8400-e29b-41d4-a716-446655440001"
    ]
  }'

Response 200

{
  "deleted": 2,
  "ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

Error Responses

Status	Error	Description
400	`bad_request`	Invalid request parameters or URL format
400	`invalid_events`	One or more event types are invalid
401	`unauthorized`	Invalid or missing authentication
404	`not_found`	Webhook or delivery not found
409	`conflict`	Webhook name already exists
429	`rate_limit_exceeded`	Too many requests

Error Response

{
  "error": "invalid_events",
  "message": "Invalid event types: invalid.event, another.bad"
}

SDK Examples

TypeScript SDK

typescript-sdk.ts

import { Trix } from '@trixdb/client';

const trix = new Trix({ apiKey: 'YOUR_API_KEY' });

// Create webhook
const webhook = await trix.webhooks.create({
  name: 'My Webhook',
  url: 'https://example.com/webhook',
  events: ['memory.created', 'memory.updated']
});

// List webhooks
const { data: webhooks } = await trix.webhooks.list({ is_active: true });

// Test webhook
const result = await trix.webhooks.test(webhook.id);

// Get deliveries
const { data: deliveries } = await trix.webhooks.getDeliveries(webhook.id, {
  status: 'failed'
});

// Retry failed delivery
await trix.webhooks.retryDelivery(webhook.id, deliveries[0].id);

// Delete webhook
await client.webhooks.delete(webhook.id);

Python SDK

python-sdk.py

from trix import Trix

client = Trix(api_key="YOUR_API_KEY")

# Create webhook
webhook = trix.webhooks.create(
    name="My Webhook",
    url="https://example.com/webhook",
    events=["memory.created", "memory.updated"]
)

# List webhooks
webhooks = client.webhooks.list(is_active=True)

# Test webhook
result = client.webhooks.test(webhook.id)

# Get deliveries
deliveries = client.webhooks.get_deliveries(
    webhook.id,
    status="failed"
)

# Retry failed delivery
client.webhooks.retry_delivery(webhook.id, deliveries.data[0].id)

# Delete webhook
client.webhooks.delete(webhook.id)

C# SDK

Program.cs

using Trix;

var trix = new TrixClient(apiKey: "YOUR_API_KEY");

// Create webhook
var webhook = await trix.Webhooks.CreateAsync(
    name: "My Webhook",
    url: "https://example.com/webhook",
    events: new[] { "memory.created", "memory.updated" }
);

// List webhooks
var webhooks = await trix.Webhooks.ListAsync(isActive: true);

// Test webhook
var result = await trix.Webhooks.TestAsync(webhook.Id);

// Get deliveries
var deliveries = await trix.Webhooks.GetDeliveriesAsync(
    webhook.Id,
    status: "failed"
);

// Retry failed delivery
await trix.Webhooks.RetryDeliveryAsync(webhook.Id, deliveries.Data[0].Id);

// Delete webhook
await trix.Webhooks.DeleteAsync(webhook.Id);