Skip to main content

Endpoints & Subscriptions

Create an endpoint​

Pass eventTypes to create the endpoint and its subscription in a single call — the usual way to start:

curl -X POST https://api.travila.ai/api/v1/webhooks/create-endpoint \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orders-service",
    "url": "https://api.example.com/hooks/travila",
    "description": "Order pipeline consumer",
    "eventTypes": ["llm.generation_completed"]
  }'

The response carries the created endpoint and, when eventTypes was supplied, the subscription.

Omit eventTypes if you want to create the subscription separately:

curl -X POST https://api.travila.ai/api/v1/webhooks/create-subscription \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "endpointId": "ep_abc123",
    "eventTypes": ["llm.generation_completed", "llm.tool_call_completed"],
    "externalId": "orders-prod"
  }'

Addressing a subscription with your own id​

externalId is optional and yours to choose — unique among live subscriptions in your tenant. Where a subscription reference is needed you may supply either subscriptionId or externalId, but exactly one; sending both, or neither, is rejected. Deleting a subscription frees its externalId for reuse.

It saves you storing our generated ids:

curl -X POST https://api.travila.ai/api/v1/webhooks/delete-subscription \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "orders-prod" }'

Managing endpoints​

List endpoints​

curl -X POST https://api.travila.ai/api/v1/webhooks/list-endpoints \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "perPage": 25}'

Response:

{
  "endpoints": [
    {
      "id": "ep_abc123",
      "name": "orders-service",
      "url": "https://api.example.com/hooks/travila",
      "description": "Order pipeline consumer",
      "status": "ENDPOINT_STATUS_ACTIVE",
      "secret": "whsec_…",
      "httpTimeout": 30,
      "createdAt": "2026-08-01T10:00:00Z",
      "updatedAt": "2026-08-01T10:00:00Z"
    }
  ],
  "pagination": {"total": 1, "page": 1, "perPage": 25, "totalPages": 1}
}

secret is the signing secret for that endpoint — this listing is where you read it back if you did not store it at creation. Treat it like a credential.

Update an endpoint​

Only the fields present in the body are modified; absent fields are left unchanged.

curl -X POST https://api.travila.ai/api/v1/webhooks/update-endpoint \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "endpointId": "ep_abc123",
    "url": "https://api.example.com/hooks/travila-v2"
  }'

Response: {"endpoint": {...}} — the updated record.

eventTypes is not settable here: what an endpoint receives lives on its subscription. To change it, delete the subscription and create a replacement (see the note below).

List subscriptions​

curl -X POST https://api.travila.ai/api/v1/webhooks/list-subscriptions \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"endpointId": "ep_abc123", "page": 1, "perPage": 25}'

Response:

{
  "subscriptions": [
    {
      "id": "sub_def456",
      "name": "orders-service-sub",
      "endpointId": "ep_abc123",
      "eventTypes": ["llm.generation_completed"],
      "externalId": "orders-prod",
      "retryConfig": {
        "strategy": "RETRY_STRATEGY_EXPONENTIAL",
        "retryCount": 5,
        "intervalSeconds": 30
      },
      "createdAt": "2026-08-01T10:00:00Z"
    }
  ],
  "pagination": {"total": 1, "page": 1, "perPage": 25, "totalPages": 1}
}

Omit endpointId to list every subscription in the tenant. This is the call to audit with — see the warning below.

One subscription per endpoint​

Keep one subscription per endpoint. A second subscription on the same endpoint double-delivers every matching event, and nothing prevents you from creating one — so if deliveries look duplicated, list subscriptions filtered by that endpointId first.

To change what an endpoint receives, delete the existing subscription and create a replacement; there is no update-subscription route. Events published in the gap between the two calls are not delivered to that endpoint.

Delete an endpoint​

curl -X POST https://api.travila.ai/api/v1/webhooks/delete-endpoint \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"endpointId": "ep_abc123"}'

Response: empty body on success.

This removes the endpoint and all its subscriptions. Delivery history for the endpoint is not replayable afterwards, so pull anything you need from list-deliveries first.