Webhooks & usage

Use webhooks to receive conversation lifecycle notifications without continuously polling history. Use the usage endpoint to inspect service usage.

Subscribe to events

POST /v1/webhooks requires webhooks:write.

{
  "url": "https://your-server.example/eva/events",
  "enabled": true,
  "event_types": ["conversation.completed", "result.ready"]
}

Supported event types are conversation.started, conversation.completed, conversation.failed, and result.ready. Use a public HTTPS endpoint. URLs containing credentials or destinations on private networks are rejected.

Creation returns the endpoint and its signing_secret once. Store the secret securely. It is separate from your API key.

Verify deliveries

Requests include:

Header	Meaning
x-eva-event-id	Event identifier for deduplication
x-eva-timestamp	Unix timestamp in seconds
x-eva-signature	v1= followed by the hexadecimal HMAC-SHA256 digest

Compute the HMAC over the ASCII timestamp, a dot, and the exact raw request body, using the signing secret as UTF-8 bytes. Compare signatures in constant time. Validate timestamp freshness with a bounded tolerance, for example five minutes; keep your server clock synchronized. Verify before parsing or processing the payload.

Treat retries as expected: deduplicate by the signed body’s event identifier and durably accept the event before returning success. A result.ready payload points to result_path; fetch the result with your scoped EVA API key.

Manage subscriptions

Method	Path	Scope
GET	/v1/webhooks	webhooks:read
GET	/v1/webhooks/{id}	webhooks:read
PATCH	/v1/webhooks/{id}	webhooks:write
DELETE	/v1/webhooks/{id}	webhooks:write
GET	/v1/webhooks/{id}/deliveries	webhooks:read

Use the delivery history to investigate failures and retries. A subscription is not validated by saving alone: exercise your receiver with a controlled test call before relying on it.

Usage summaries

GET /v1/usage requires usage:read.

Optional filters include start, end, agent_id, conversation_id, provider, model, capability, and status. Use ISO 8601 timestamps for the date filters.

Service usage quantities and provider cost estimates are different from the customer-facing call-minute allowance on Budget. Missing cost information should not be treated as a zero cost.