Inbound Webhooks

The api app carries two inbound webhook routes.

Payment events

Payment events arrive at POST /webhooks/payments in the api app. The route constructs the event and switches on its type.

Authentication events

Authentication events arrive at POST /webhooks/auth in the api app.

Local development

Clerk webhooks cannot be forwarded to localhost. Test them against a deployed environment — the API Worker running development environment variables, for example staging-api.example.com — and register that URL in the Clerk webhook settings. Currently there's no way to easily test Clerk webhooks locally, so you'll have to test them in a staging environment. This means deploying the API Worker with development environment variables, e.g. staging-api.example.com. Then you can add this URL to your Clerk project's webhook settings.

Database Events

One of the most common use cases for inbound webhooks is to notify your application when a database record is created, updated, or deleted. This allows you to react to changes asynchronously, rather than polling the database, cron jobs or other methods.

Some providers offer this natively — Supabase, for example, has Database Webhooks.