Langfuse Webhook Guide ⚓

🚀 Quick Start

Langfuse provides real-time webhooks for prompt lifecycle events (created, updated, deleted). They eliminate API polling to automate CI/CD pipelines, sync catalogs, and trigger notifications. Setup requires a POST HTTPS endpoint to accept payloads. Configure the URL and event filters within the Langfuse UI under Prompts > Automations.

🔧 Configuration

Langfuse secures payloads using an HMAC SHA-256 hash. The signature is transmitted via the x-langfuse-signature header.

// Node.js Example Signature Verification
const expected = crypto
  .createHmac("sha256", process.env.LANGFUSE_WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex")
const isValid = crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))

Store LANGFUSE_WEBHOOK_SECRET securely in environment variables. Filter webhooks by specific prompt actions to reduce noise.

💡 Best Practices

Always compute the HMAC using the raw, unparsed request body. Parsing the body to JSON before hashing alters whitespace and breaks verification. Use a timing-safe comparison function to prevent timing attacks. Connect webhook triggers to label updates (e.g., “production”) for deployment workflows via GitHub repository_dispatch.

🚨 Gotchas / Warnings

Webhooks do not propagate to parent prompts when a referenced child prompt (e.g., {{ref:child}}) is updated. Only the child prompt update triggers an event. Prompt Webhooks are distinct from “Web Callouts”, which are manually triggered ad-hoc actions. Signature headers might not be present or identical across all Langfuse features, such as Remote Dataset Runs.

🔍 Research / References

• Docs: Langfuse Webhooks
• Auth: HMAC SHA-256 signature verification via x-langfuse-signature.