Connect Your Backend

Layercode is designed for maximum flexibility: you can connect any backend that can receive an HTTP request and return a Server-Sent Events (SSE) stream. This allows you to use your own LLM-powered agent, business logic, or orchestration—while Layercode handles all the real-time voice infrastructure.

​

How it works

By default, Layercode pipelines use our Hosted Backend (powered by Gemini Flash 2.0). To use your own backend, click the “Connect Your Backend” button on your pipeline, and then set the Webhook URL to point to your backend’s endpoint.

When a user interacts with your voice agent, Layercode will:

1. Transcribe the user’s speech to text.
2. Send an HTTP POST request to your backend at the Webhook URL you provide.
3. Your backend responds with a Server-Sent Events (SSE) stream containing the agent’s reply (text to be spoken, and optional data).
4. Layercode handles converting the text in your response to speech and streaming it back to the user in real time.
5. Return of JSON data is also supported to allow you to pass state back to your UI.

​

Configuring Your Pipeline

1. In the Layercode dashboard, open your pipeline and click Connect Your Backend (or click the edit button in the Your Backend box if you’ve already connected your backend previously).
2. Enter your backend’s Webhook URL in the configuration modal.
3. Optionally, configure which webhook events you want to receive (see below).
4. Save your changes.

​

Webhook Events

• message (required):
  Sent when the user finishes speaking. Contains the transcribed message and metadata. Your backend should respond with an SSE stream containing the agent’s reply.
• session.start (optional):
  Sent when a new session is started (e.g., when a user connects). Use this to have your agent start the conversation. If disabled, the agent will wait for the user to speak first when a new session is started.

​

Webhook Verification

To ensure the security of your backend, it’s crucial to verify that incoming requests are indeed from Layercode. This can be done by verifying the layercode-signature header, which contains a timestamp and a HMAC-SHA256 signature of the request body.

Here’s how you can verify the signature in your backend:

1. Retrieve the layercode-signature header from the request. It will be in the format: t=timestamp,v1=signature.
2. Get your Layercode webhook secret from the Layercode dashboard (found by going to the appropriate pipeline and clicking the edit button in the Your Backend box, where you’ll find the Webhook Secret).
3. Reconstruct the signed payload by concatenating the timestamp, a period (.), and the exact raw webhook request body: signed_payload = timestamp + "." + request_body.
4. Compute the HMAC-SHA256 signature of this signed payload using your webhook secret.
5. Compare the computed signature with the v1 value from the layercode-signature header. If they match, the request is valid.
6. (Recommended) Check that the timestamp is recent (for example, within 5 minutes) to prevent replay attacks.

See the example code snippets in our Backend Guides for framework-specific implementations.

​

Example: Webhook Request

When a user finishes speaking, Layercode will send a POST request to your webhook with the following JSON payload body:

{
  "type": "message", // The type of webhook event: message or session.start
  "session_id": "uuid", // Session ID is unique per conversation. Use this to know which conversation a webhook belongs to.
  "turn_id": "uuid", // Turn ID is unique per turn of the conversation. This ID must be returned in all SSE events. It is unique per turn of the conversation.
  "text": "What's the weather today?" // The user's transcribed message
}

See the Webhook SSE API documentation for details

​

Example: SSE Response

Your backend should respond with an SSE stream. Each SSE message contains a JSON payload with the following fields: type, content (when required) and turn_id. See the Webhook SSE API documentation for details.

Below is a simple example where we respond with a static text SSE event, which will be converted to speech and spoken to the user:

import express from "express";
import { streamResponse } from "@layercode/node-server-sdk";

const app = express();
app.use(express.json());

app.post("/agent", async (req, res) => {
  return streamResponse(req.body, async ({ stream }) => {
    stream.tts("Hi, how can I help you today?");
    stream.end();
  });
});

​

Backend Guides

Layercode supports any backend that can handle HTTP POST and SSE, including popular frameworks and languages. Check out our step-by-step guides for different backend types:

Looking for another stack? Any backend that can handle HTTP POST and respond with SSE will work with Layercode. See the Webhook SSE API documentation for details.

​

Integrating with Your Frontend

Once you’ve integrated Your Backend, you can build web and mobile voice AI applications by integrating with one of our Frontend SDKs. Learn how to Build a Web Voice Agent.

​

Integrating with Telephony

You can also build voice AI applications that can be used over the phone. Learn how to Build a Phone Agent (coming soon).