Webhook Reliability: Admin Access Webhook#

Overview#

The admin access webhook (adminAccessWebhook.ts) fires an HTTP notification whenever a Langfuse admin user accesses a project or trace they are not a member of. It is configured via the LANGFUSE_ADMIN_ACCESS_WEBHOOK environment variable. The webhook call is fire-and-forget: errors are logged but never surfaced to the caller.

Key Files#

How It Works#

sendAdminAccessWebhook is called from three tRPC authorization middlewares in trpc.ts:

• enforceUserIsAuthedAndProjectMember — fires when an admin accesses a project they are not a session member of 1, and also when the admin is a session member 2.
• enforceTraceAccess — fires when an admin accesses any trace 3.
• enforceSessionAccess — fires when an admin accesses any trace session 4.

These map to the exported procedures protectedProjectProcedure, protectedGetTraceProcedure, and protectedGetSessionProcedure 5 6 7.

Known Reliability Issues#

1. Deduplication Timing Bug#

The dedupe key is recorded in lastWebhookByKey before the fetch call completes 8. If the POST request fails (network error, timeout, non-2xx response), the dedup window is still consumed — subsequent calls within the 5-minute window are silently dropped without retrying. The dedup window is hardcoded to 5 minutes 9. The correct fix is to record the key only after a successful response.

2. Missing Fetch Timeout#

fetch is called with no signal / AbortController timeout 10. If the webhook endpoint is unresponsive, the await fetch(...) hangs indefinitely. Because sendAdminAccessWebhook is await-ed inside the tRPC authorization middleware before next() is called, a hung fetch will stall every middleware execution and block the request for the full lifecycle of the TCP connection — potentially exhausting the Node.js event loop under load.

3. Test Coverage Gaps#

The existing test suite covers normal flow and basic error paths 11, but does not exercise:

• The dedupe timing bug: no test verifies that a failed fetch does not consume the dedupe window.
• Fetch timeout behavior: no test simulates a hanging fetch or asserts that the middleware resolves within a bounded time.
• The enforceIsAuthedAndOrgMember path (org-level admin access webhook) is not covered by the middleware integration tests 12.

Deduplication Details#

The dedup key is email:project:org 13. The cache (lastWebhookByKey) is a module-level Map — it is process-local and does not survive restarts or span multiple server instances. resetAdminAccessWebhookCacheForTests() is exposed for test teardown 14.

Webhook Payload Shape#

type AdminAccessWebhookPayload = {
  email: string;
  timestamp: string; // ISO 8601
  project: string | null;
  org: string | null;
  region: string; // NEXT_PUBLIC_LANGFUSE_CLOUD_REGION or "self-hosted"
};

15

Suggested Fixes#

1. Dedupe after success: Move lastWebhookByKey.set(...) inside the try block, after confirming response.ok.
2. Add a fetch timeout: Wrap the fetch call with an AbortSignal.timeout(...) (Node 18+) to bound the maximum wait.
3. Add regression tests: Test that a failed fetch does not block re-sends within the dedupe window, and that the middleware does not hang when fetch never resolves.