Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.layercode.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide shows you how to implement the Layercode Webhook SSE API in an ExpressJS backend. You’ll learn how to set up a webhook endpoint that receives transcribed messages from the Layercode voice agent and streams the agent’s responses back to the frontend, to be turned into speech and spoken back to the user. You can test your backend using the Layercode dashboard playground or by following the Build a Web Voice Agent guide. Example code: layercodedev/example-backend-express

​
Prerequisites

  • Node.js 18+
  • Express
  • A Layercode account and agent (sign up here)
  • (Optional) An API key for your LLM provider (we recommend Google Gemini)

​
Setup

npm install express @layercode/node-server-sdk ai @ai-sdk/google node-fetch
Edit your .env environment variables. You’ll need to add:
  • GOOGLE_GENERATIVE_AI_API_KEY - Your Google AI API key
  • LAYERCODE_WEBHOOK_SECRET - Your Layercode agent’s webhook secret, found in the Layercode dashboard (go to your agent, click Edit in the Your Backend Box and copy the webhook secret shown)
  • LAYERCODE_API_KEY - Your Layercode API key found in the Layercode dashboard settings

​
Create Your Express Webhook Endpoint

Here’s an example of a our Layercode webhook endpoint, which generates responses using Google Gemini and streams them back to the frontend as SSE events. See the GitHub repo for the full example. 
import type { RequestHandler } from 'express';
import { createGoogleGenerativeAI } from '@ai-sdk/google';
import { streamText } from 'ai';
import type { CoreMessage } from 'ai';
import { verifySignature, streamResponse } from '@layercode/node-server-sdk';
import { Readable } from 'node:stream'; // Node.js 18+ only

const google = createGoogleGenerativeAI({
  apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY,
});

const sessionMessages: Record<string, CoreMessage[]> = {};

const SYSTEM_PROMPT =
  "You are a helpful conversation assistant. You should respond to the user's message in a conversational manner. Your output will be spoken by a TTS model. You should respond in a way that is easy for the TTS model to speak and sound natural.";
const WELCOME_MESSAGE = 'Welcome to Layercode. How can I help you today?';

export const onRequestPost: RequestHandler = async (req, res) => {
  const requestBody = req.body;
  const signature = req.header('layercode-signature') || '';
  const secret = process.env.LAYERCODE_WEBHOOK_SECRET || '';
  const payload = JSON.stringify(requestBody);
  const isValid = verifySignature({ payload, signature, secret });
  if (!isValid) {
    console.error('Invalid signature', signature, secret, payload);
    res.status(401).send('Unauthorized');
    return;
  }
  console.log('Request body received from Layercode', requestBody);
  const { session_id, text, type } = requestBody;

  let messages = sessionMessages[session_id] || [];
  messages.push({ role: 'user', content: [{ type: 'text', text }] });

  let response;
  if (type === 'session.start') {
    response = streamResponse(requestBody, async ({ stream }: { stream: any }) => {
      stream.tts(WELCOME_MESSAGE);
      messages.push({
        role: 'assistant',
        content: [{ type: 'text', text: WELCOME_MESSAGE }],
      });
      stream.end();
    });
  } else {
    response = streamResponse(requestBody, async ({ stream }: { stream: any }) => {
      try {
        const { textStream } = streamText({
          model: google('gemini-2.0-flash-001'),
          system: SYSTEM_PROMPT,
          messages,
          onFinish: async ({ response }: { response: any }) => {
            messages.push(...response.messages);
            console.log('Current message history for session', session_id, JSON.stringify(messages, null, 2));
            sessionMessages[session_id] = messages;
          },
        });
        stream.data({
          textToBeShown: 'Hello, how can I help you today?',
        });
        await stream.ttsTextStream(textStream);
      } catch (err) {
        console.error('Handler error:', err);
      } finally {
        console.log('Stream ended');
        stream.end();
      }
    });
  }

  // Set headers and status
  response.headers.forEach((value, key) => res.setHeader(key, value));
  res.status(response.status);

  if (response.body) {
    const nodeStream = Readable.fromWeb(response.body as any);
    nodeStream.pipe(res);
  } else {
    res.end();
  }
};

​
3. How It Works

  • /agent endpoint: Receives POST requests from Layercode with the user’s transcribed message, session, and turn info.
  • Session management: Keeps track of conversation history per session (in-memory for demo; use a store for production).
  • LLM call: Calls Google Gemini (or your own agent) with the conversation history and streams the response.
  • SSE streaming: Streams the agent’s response back to Layercode as Server-Sent Events, which are then converted to speech and played to the user.
  • /authorize endpoint: Your Layercode API key should never be exposed to the frontend. Instead, your backend acts as a secure proxy: it receives the frontend’s request then, calls the Layercode authorization API using your secret API key, and finally returns the client_session_key (and optionally a conversation_id) to the frontend. This key is required for the frontend to establish a secure WebSocket connection to Layercode.

​
Running Your Backend

Start your Express server: 
npx tsx index.ts

​
Configure the Layercode Webhook endpoint

In the Layercode dashboard, go to your agent settings. Under Your Backend, click edit, and here you can set the URL of the webhook endpoint. If running this example locally, setup a tunnel (we recommend cloudflared which is free for dev) to your localhost so the Layercode webhook can reach your backend. Follow our tunnelling guide.