Webhooks and Public Routes

Webhook Management Routes

Athena exposes webhook management under the admin surface:

GET /admin/webhooks
POST /admin/webhooks
GET /admin/webhooks/events
GET /admin/webhooks/{id}
PATCH /admin/webhooks/{id}
DELETE /admin/webhooks/{id}
GET /admin/webhooks/{id}/deliveries
POST /admin/webhooks/{id}/test

Auth requirements:

X-Athena-Client
x-athena-admin-key

Public Route Management

Public route registration is managed via admin endpoints:

GET /admin/public-routes
POST /admin/public-routes
PATCH /admin/public-routes/{route_key}
DELETE /admin/public-routes/{route_key}

Public invocation is served through:

POST /public/{route_key}/{op} where {op} is one of query, fetch, insert, update, delete.

Tenant wildcard hostnames

Athena can also use public_gateway_routes as the resolution layer for hostname-based HTTP routing.

Canonical shape: tenant.v3.athena-cluster.com
Onboarding route: PUT /admin/tenant-hostnames/{tenant}
Resolution source: active public_gateway_routes rows only

This endpoint can upsert the HTTP route alias and, optionally, persist the matching PostgreSQL public-host metadata into the target Athena client record. Athena does not proxy raw PostgreSQL traffic on that hostname by itself.

See Tenant Wildcard Hostnames for the full runbook and request examples.

Recommended Workflow

Create webhook endpoint and secret handling in your receiving service.
Register webhook via /admin/webhooks.
Trigger test delivery via /admin/webhooks/{id}/test.
Inspect delivery logs using /admin/webhooks/{id}/deliveries.
Register public routes only for operations that are explicitly safe to expose.

Reference

Use Reference -> Athena API Reference -> admin and public sections for operation-level schemas and response envelopes.