Overview

Webhooks allow you to receive real-time notifications when events happen in your Contox project. When an event occurs, Contox sends an HTTP POST request to your configured endpoint with details about the event.

Managing webhooks

Create webhook

POST /api/webhooks

Request body

Field	Type	Required	Description
`url`	string	Yes	The HTTPS endpoint URL to receive events
`events`	array	Yes	Array of event types to subscribe to
`projectId`	string	Yes	The project ID
`secret`	string	No	A secret for verifying webhook signatures

Example

bash

curl -X POST https://contox.dev/api/webhooks \
  -H "Authorization: Bearer contox_sk_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/contox",
    "events": ["session.completed", "enrichment.completed", "item.created"],
    "projectId": "proj_abc123",
    "secret": "whsec_your_webhook_secret"
  }'

Response

json

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/contox",
  "events": ["session.completed", "enrichment.completed", "item.created"],
  "status": "active",
  "createdAt": "2025-01-20T14:00:00Z"
}

List webhooks

GET /api/webhooks

Update webhook

PATCH /api/webhooks/[id]

Delete webhook

DELETE /api/webhooks/[id]

Event types

Event	Trigger
`session.created`	A new session is created
`session.completed`	A session is marked as completed
`enrichment.started`	Enrichment pipeline begins processing
`enrichment.completed`	Enrichment pipeline finishes successfully
`enrichment.failed`	Enrichment pipeline encounters an error
`item.created`	A new memory item is extracted
`item.updated`	A memory item is modified
`item.deprecated`	A memory item is deprecated
`brain.updated`	The project brain is updated
`member.added`	A new member joins the project
`member.removed`	A member is removed from the project

Payload format

All webhook payloads follow a consistent structure:

json

{
  "id": "evt_abc123def456",
  "type": "enrichment.completed",
  "projectId": "proj_abc123",
  "timestamp": "2025-01-20T14:00:00Z",
  "data": {
    "sessionId": "sess_xyz789",
    "itemsExtracted": 8,
    "duration": 7100
  }
}

Field	Type	Description
`id`	string	Unique event identifier
`type`	string	The event type
`projectId`	string	The project this event belongs to
`timestamp`	string	ISO 8601 timestamp
`data`	object	Event-specific data

Verifying signatures

If you provided a secret when creating the webhook, each delivery includes a signature header for verification:

X-Contox-Webhook-Signature: sha256=abc123...

Verify the signature using HMAC-SHA256:

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return `sha256=${expected}` === signature;
}

Always verify webhook signatures in production to ensure requests originate from Contox.

Retry behavior

Failed webhook deliveries are retried with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

A delivery is considered failed if:

The endpoint returns a non-2xx status code
The request times out after 30 seconds
The endpoint is unreachable

After 5 failed retries, the delivery is marked as failed and no further attempts are made. Consistently failing webhooks may be automatically disabled.

Best practices

Use HTTPS -- Webhook endpoints must use HTTPS for security
Verify signatures -- Always validate the X-Contox-Webhook-Signature header
Return 200 quickly -- Acknowledge the webhook promptly and process the event asynchronously
Handle duplicates -- Use the event id for idempotency, as retries may deliver the same event more than once
Monitor failures -- Check your webhook status in the dashboard regularly

Next steps

API Overview -- General API information
V2 Sessions -- Session endpoints that trigger webhook events

Billing

Overview

On this page