Add webhook event bus for async processing

[cb-srinaths]

The current implementation only supports synchronous processing of webhook events. If an application was to follow our best practices and save the incoming events to an event bus and then process it, all the default subscription handlers will have to be duplicated. This PR abstracts the processing of the webhook from the way the events are triggered. This will let apps implement an async flow: Chargebee -> App -> Queue -> Worker -> Process Better Auth related events.

Introduce a Chargebee webhook event bus and processor for async queue/worker flows. Add webhook event-bus types, re-exports, and an async processor factory. Refactor the webhook endpoint to dispatch validated events or publish to the bus when configured, plus tests for publish and processing behavior.

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Enterprise

Run ID: 129e097f-1324-4685-86c6-d6f76c349fe1

📥 Commits

Reviewing files that changed from the base of the PR and between 2bfcfa8 and 2c01401.

📒 Files selected for processing (2)

• packages/better-auth/package.json
• packages/better-auth/src/webhook-handler.ts

✅ Files skipped from review due to trivial changes (1)

• packages/better-auth/package.json

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/better-auth/src/webhook-handler.ts

---

Walkthrough

The PR adds Chargebee webhook event-bus support, updates webhook event types and options, refactors webhook handling into shared dispatch and publish paths, adds a webhook processor factory, updates route wiring, and extends tests for publish and processor behavior.

Changes

Chargebee webhook API surface

Layer / File(s)	Summary
Webhook types and exports packages/better-auth/src/types.ts, packages/better-auth/src/webhook-processor.ts, packages/better-auth/src/index.ts, packages/better-auth/package.json	WebhookEvent now aliases Chargebee’s webhook event type, ChargebeeWebhookEventBus and processor contracts are added, ChargebeeOptions gains webhookEventBus, public exports are extended, and the package version changes to 1.2.0.
Webhook dispatch and publish handler packages/better-auth/src/webhook-handler.ts, packages/better-auth/test/webhook-queue.test.ts	Webhook validation and event dispatch are centralized, and a publish handler forwards handled and unhandled events to an event bus; tests cover publish routing and HTTP responses.
Route selection packages/better-auth/src/routes.ts	Webhook route construction now selects the publish handler or synchronous handler based on options.webhookEventBus.
Processor implementation and tests packages/better-auth/src/webhook-processor.ts, packages/better-auth/test/webhook-queue.test.ts	A webhook processor resolves explicit or lazy context and dispatches Chargebee events, with tests covering adapter processing, lazy context, and unknown events.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Chargebee
  participant WebhookRoute
  participant EventBus
  participant WebhookProcessor
  participant Adapter

  Chargebee->>WebhookRoute: Send validated webhook
  WebhookRoute->>EventBus: Publish WebhookEvent
  EventBus->>WebhookProcessor: Process WebhookEvent
  WebhookProcessor->>Adapter: Run matching DB-sync hook

Loading

🚥 Pre-merge checks | ✅ 1

✅ Passed checks (1 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/better-auth/src/webhook-handler.ts`:
- Around line 47-55: buildRequestValidator currently falls back to undefined
when only one of webhookUsername or webhookPassword is set, which disables Basic
Auth and leaves webhooks unauthenticated. Update buildRequestValidator in
webhook-handler.ts to fail closed by validating the webhook auth config up
front: if either credential is provided without the other, treat it as an error
instead of returning undefined. Keep basicAuthValidator only for the fully
configured case, and ensure the webhook-handler path rejects partial/empty auth
configuration rather than accepting requests without auth.
- Around line 298-323: The webhook handlers for handled and unhandled events
currently await eventBus.publish(event) and rely on the shared
handler.on("error") path, which converts every non-authentication failure into
200 OK. Update the event publishing flow in webhook-handler.ts so publish
failures are not acknowledged: handle errors from eventBus.publish(event)
explicitly in the HANDLED_EVENT_TYPES and "unhandled_event" listeners, and
ensure those queueing failures either rethrow or send a non-2xx response instead
of falling through to the generic 200 OK path.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 91ba27d8-d462-4cb3-b3f1-f26664642907

📥 Commits

Reviewing files that changed from the base of the PR and between 27e172a and 1136a4b.

📒 Files selected for processing (6)

• packages/better-auth/src/index.ts
• packages/better-auth/src/routes.ts
• packages/better-auth/src/types.ts
• packages/better-auth/src/webhook-handler.ts
• packages/better-auth/src/webhook-processor.ts
• packages/better-auth/test/webhook-queue.test.ts