Webhooks

HermesAI currently depends on two external webhooks in production. Both are signed and validated server-side before any state mutation.

Production prerequisite

The deployed environment must contain both webhook secrets. Failures should never be quietly masked as auth or availability issues — surface them.

Endpoint

POST /api/billing/webhooks/polar

Required environment variable

POLAR_WEBHOOK_SECRET

Events handled

subscription.created
subscription.updated
subscription.active
subscription.canceled
subscription.uncanceled
subscription.revoked
order.created
order.updated
order.paid
order.refunded

What it updates

Tenant subscription plan
Tenant subscription status
Billing invoice records

Endpoint

POST /api/webhooks/clerk

Required environment variable

CLERK_WEBHOOK_SIGNING_SECRET

Events handled

user.created
user.updated
user.deleted
organization.created
organization.updated
organization.deleted
organizationMembership.created
organizationMembership.updated
organizationMembership.deleted

What it updates

Clerk user snapshots
Organization snapshots
Tenant membership snapshots

Verification checklist

Confirm both secrets are wired

Both POLAR_WEBHOOK_SECRET and CLERK_WEBHOOK_SIGNING_SECRET must be present in the deployed environment.

Polar deliveries return `200`

Inspect the Polar dashboard's webhook delivery log. Repeated 4xx or 5xx responses indicate signature mismatch or runtime failure.

Clerk deliveries return `200`

Inspect Clerk's webhook log. The signing secret must match exactly — re-roll if there's any doubt.

Failures surface, not hide

Both routes use signature verification + idempotency keys. Failed processing should be visible in billing_webhook_events / clerk_webhook_events audit tables, not swallowed.

On this page