Deliver account, quota, and deployment signals out of Eventium.

Contents

1. Overview
2. Event catalog
3. Payload contract
4. Signature verification
5. Endpoint lifecycle
6. Retries and idempotency
7. Testing
8. SDK and server examples

Overview

A webhook endpoint is an HTTPS URL you own. When a subscribed event occurs, Eventium delivers an HTTP POST with a JSON body and signature headers. Your endpoint should validate the signature, queue work quickly, and return a 2xx response.

Event catalog

GET /api/webhooks/events

Payload contract

Every delivery includes the same envelope. Only the data object varies by event type.

{
  "id": "0c3b1d5b-1d66-4a16-b2b5-7aa3c2c9b5ab",
  "type": "quota.threshold.reached",
  "created_at": "2026-05-26T09:14:02Z",
  "data": {
    "scope": "daily",
    "threshold": 80,
    "limit": 10000,
    "count": 8123,
    "plan": "builder"
  }
}

Signature verification

Deliveries are signed with HMAC SHA-256. The header format is currently X-TitanVX-Signature: t=<unix>,v1=<hex>. The header name remains the same for compatibility, even though the delivery surface is now documented as Eventium.

secret = "YOUR_ENDPOINT_SECRET"
sig = request.headers["X-TitanVX-Signature"]
raw_body = request.get_data()

if not verify_signature(secret, sig, raw_body):
    abort(400)

Endpoint lifecycle

POST   /api/webhooks/endpoints
GET    /api/webhooks/endpoints
PATCH  /api/webhooks/endpoints/{id}
DELETE /api/webhooks/endpoints/{id}

GET    /api/webhooks/deliveries
POST   /api/webhooks/test
GET    /api/webhooks/events

Retries and idempotency

• Treat deliveries as at-least-once.
• Use the delivery id as your idempotency key.
• Return 2xx quickly after queueing work.
• Inspect GET /api/webhooks/deliveries for last error, status, and retry timing.

Testing

You can validate your handler in three ways: use the webhook management page, call the REST endpoint directly, or trigger it from the Python SDK.

POST /api/webhooks/test
{
  "event_type": "webhook.test",
  "data": {
    "hello": "world"
  }
}

SDK and server examples

Python SDK

from titanvx_sdk import TitanVxClient

client = TitanVxClient(
    base_url="https://api.eventium.ai",
    bearer_token="YOUR_JWT",
)

client.webhooks.create_endpoint(
    url="https://example.com/eventium/webhooks",
    events=["quota.threshold.reached", "agent.deployment.updated"],
)

client.webhooks.test(
    event_type="webhook.test",
    data={"hello": "world"},
)

FastAPI verification example

from fastapi import FastAPI, Header, HTTPException, Request
from titanvx_sdk.webhooks import verify_signature

app = FastAPI()
SECRET = "YOUR_ENDPOINT_SECRET"

@app.post("/eventium/webhooks")
async def eventium_webhook(request: Request, x_titanvx_signature: str = Header("")):
    body = await request.body()
    if not verify_signature(SECRET, x_titanvx_signature, body):
        raise HTTPException(status_code=400, detail="Invalid signature")
    payload = await request.json()
    return {"ok": True, "type": payload.get("type")}