Handling Webhooks

Introduction

Webhooks are a way for your app to receive events from Langburp.

You technically don't need to setup webhooks for your app to work. They are only necessary if you need to receive events from Langburp, for example, when a user sends a message to your chat app.

Configuring Your Webhook URL in Langburp

Before you can receive webhooks, you'll need to configure your webhook URL in your Langburp project.

Navigate to the Webhook tab in your Langburp project (under the Settings section in the sidebar).
Click the Add Webhook button.
Enter the URL of your webhook. This should be a publicly accessible HTTPS endpoint that can receive POST requests (e.g. https://your-domain.com/api/langburp/webhook).
Click the Save button.

During development, you can use ngrok to expose your local server to the internet. After installing ngrok, run ngrok http 3000 to get a public URL that forwards to your local server (e.g. https://abc123.ngrok.io/api/langburp/webhook). Use this URL as your webhook URL in the Langburp Console.

Using the JS/TS Webhook SDK

Installation

npm install @langburp/webhook

Receiving Webhooks in NextJS (App Router)

/app/api/langburp/webhook/route.ts

import { NextResponse } from 'next/server';
import { LangburpWebhookResponder } from '@langburp/webhook';
 
export async function POST(request: Request) {
  // Get the raw body text for signature verification
  const rawBody = await request.text();
 
  const responder = new LangburpWebhookResponder({
    secretApiKey: process.env.LANGBURP_SECRET_API_KEY!,
    publicApiKey: process.env.NEXT_PUBLIC_LANGBURP_PUBLIC_API_KEY!,
  });
 
  responder.message(/.*/, async ({ payload, respond }) => {
    console.log('Message received:', payload.text);
    await respond({
      text: 'Hello!',
    });
  });
 
  try {
    // Parse, verify, and handle the webhook
    await responder.handle({
      rawBody,
      headers: request.headers
    });
 
    // Return a 200 response to Langburp to confirm receipt of the webhook
    return NextResponse.json({ message: 'ok' }, { status: 200 });
  } catch (error) {
    console.error('Error processing webhook:', error);
 
    return NextResponse.json(
      { error: 'Error processing webhook' },
      { status: 500 }
    );
  }
}

Receiving Webhooks in Express

server.ts

import express from 'express';
import { LangburpWebhookResponder } from '@langburp/webhook';
 
const app = express();
 
app.use(
  express.json({
    verify: (req, _, buf) => {
      // Store raw body as string (for slack verification)
      (req as any).rawBody = buf;
    },
  })
);
 
app.post('/api/langburp/webhook', async (req: Request, res: Response) => {
  const responder = new LangburpWebhookResponder({
    secretApiKey: process.env.LANGBURP_SECRET_API_KEY!,
    publicApiKey: process.env.NEXT_PUBLIC_LANGBURP_PUBLIC_API_KEY!,
  });
 
  responder.message(/.*/, async ({ payload, respond }) => {
    console.log('Message received:', payload.text);
    await respond({
      text: 'Hello!',
    });
  });
 
  try {
    // Parse, verify, and handle the webhook
    await responder.handle({
      rawBody: (req as any).rawBody,
      headers: req.headers
    });
 
    // Respond with a 200 to confirm successful receipt of the webhook
    res.status(200).send('ok');
  } catch (error) {
    console.error('Error processing webhook:', error);
    res.status(500).send('Error processing webhook');
  }
});