Hello world: webhook routing

With webhook routing, Wassist hands every inbound WhatsApp message to your endpoint and doesn’t run an agent. Your code decides what to say and replies with one API call. Use it to connect an agent you’ve already built (LangChain, the OpenAI Agents SDK, Vercel eve, or your own) or any backend logic. By the end of this page you’ll send “hi” to the sandbox number and your own server will reply “Hello, world! You said: hi”.

Use your personal organization while testing on the sandbox (switch in Settings → Organization), and create the API key and webhook there. Sandbox chats are filed under your personal organization, so routing set up in a team organization won’t receive your messages.

1. Get an API key

In the dashboard, go to Settings → Developers → API keys, click Create API key and copy it. Your server uses it to send replies.

2. Write the handler

The handler verifies the signature, then replies to every routed message.

Node.js
Python

npm install @wassist/sdk express

server.mjs

import express from "express";
import { Wassist } from "@wassist/sdk";

const wassist = new Wassist({ apiKey: process.env.WASSIST_API_KEY });
const app = express();

// Keep the raw body: the signature is computed over the exact bytes.
app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = Wassist.webhooks.constructEvent(
      req.body,
      req.header("x-wassist-signature"),
      process.env.WASSIST_WEBHOOK_SECRET,
    );
  } catch {
    return res.status(400).send("bad signature");
  }

  if (event.event === "subscription.message.received") {
    await wassist.conversations.messages.send(event.conversationId, {
      type: "text",
      text: { body: `Hello, world! You said: ${event.message.body ?? "(no text)"}` },
    });
  }

  res.sendStatus(200);
});

app.listen(3000, () => console.log("Listening on http://localhost:3000/webhook"));

pip install flask requests

server.py

import hashlib, hmac, os, time

import requests
from flask import Flask, request

API = "https://backend.wassist.app/api/v1"
app = Flask(__name__)


def verified(req) -> bool:
    header = req.headers.get("X-Wassist-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    ts, received = parts.get("t", "0"), parts.get("v1", "")
    signed = f"{ts}.".encode() + req.get_data()
    secret = os.environ["WASSIST_WEBHOOK_SECRET"].encode()
    expected = hmac.new(secret, signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(received, expected) and abs(time.time() - int(ts)) <= 300


@app.post("/webhook")
def webhook():
    if not verified(request):
        return "bad signature", 400

    event = request.get_json()
    if event["event"] == "subscription.message.received":
        text = event["message"]["body"] or "(no text)"
        requests.post(
            f"{API}/conversations/{event['conversationId']}/messages/",
            headers={"X-API-Key": os.environ["WASSIST_API_KEY"]},
            json={"type": "text", "text": {"body": f"Hello, world! You said: {text}"}},
            timeout=10,
        )

    return "ok", 200


if __name__ == "__main__":
    app.run(port=3000)

3. Expose it over HTTPS

Wassist needs a public URL to deliver to. Locally, a tunnel is the quickest option:

ngrok http 3000

Copy the https://…ngrok.app URL it prints. Any HTTPS host works too: Vercel, Cloudflare Workers, Railway, your own server.

4. Create the webhook

Add the webhook

Go to Settings → Developers → Webhooks and click Create webhook. Set the URL to your tunnel plus /webhook, e.g. https://abc123.ngrok.app/webhook.

Keep the routing event ticked

All events are ticked by default. Make sure Subscription message received stays on. That’s the event routed messages arrive as, and a webhook without it silently gets nothing.

Copy the signing secret

The secret is shown once, straight after you create the webhook.

Now start the server with both values:

WASSIST_API_KEY=your-api-key WASSIST_WEBHOOK_SECRET=your-signing-secret node server.mjs

WASSIST_API_KEY=your-api-key WASSIST_WEBHOOK_SECRET=your-signing-secret python server.py

5. Route the sandbox to your webhook

Open the sandbox number

Go to Numbers and click the number under Sandbox numbers.

Switch routing to your webhook

In Routing, set Mode to Webhook: forward to your endpoint, pick the webhook you just created, and click Save routing.

This only affects your own chat with the sandbox number. Sandbox routing has to be set from the dashboard. API keys belong to the organization rather than a person, so they have no chat to route and get a 400.

6. Say hi

From the phone you signed in with, send hi to the sandbox number:

You:          hi
Your server:  Hello, world! You said: hi

Your code is now answering WhatsApp. Every delivery, including the request, your response and any retries, is listed under Settings → Developers → Webhooks → your webhook, where you can also replay it.

What your endpoint receives

{
  "event": "subscription.message.received",
  "timestamp": "2026-09-26T08:15:00.000000+00:00",
  "conversationId": "5a3f…e2",
  "whatsappNumber": "447700900100",
  "contact": { "id": "c81d…4b", "name": "Alex", "phoneNumber": "447700900200" },
  "message": {
    "id": "01HXYZ…",
    "body": "hi",
    "media": [],
    "buttons": [],
    "referral": null
  },
  "latestReferral": null,
  "routing": "webhook",
  "webhookId": "9c1c…a0"
}

message.body is the text (or the image caption, or the voice note transcription). Images and voice notes also arrive as URLs in media, and tapped buttons in buttons. Use conversationId for everything you send back.

Reply within 10 seconds and do slow work (like calling an LLM) after you’ve returned 200. Wassist retries on 5xx and timeouts, so use the X-Wassist-Delivery header to skip duplicates. See Webhooks for signing, retries and replay.

Make it an agent

Swap the hello world line for your own logic. A typical handler shows a typing indicator, calls your agent, then replies:

if (event.event === "subscription.message.received") {
  res.sendStatus(200); // acknowledge first, work second

  await wassist.conversations.typing(event.conversationId);
  const reply = await myAgent.run(event.message.body, { threadId: event.conversationId });
  await wassist.conversations.messages.send(event.conversationId, {
    type: "text",
    text: { body: reply },
  });
  return;
}

Replies can also carry images, buttons and CTAs. See Send message. WhatsApp only allows free-form replies within 24 hours of the customer’s last message. After that, send an approved template.

Using Vercel eve

If your agent is built with Vercel eve, you don’t need to write the handler at all. @wassist/eve is a drop-in channel that verifies webhooks, shows typing indicators and sends replies:

agent/channels/whatsapp.ts

import { wassistChannel } from "@wassist/eve";

export default wassistChannel();

It reads WASSIST_API_KEY and WASSIST_WEBHOOK_SECRET from the environment and listens on /eve/v1/wassist. Point your webhook there and follow step 5 above.

Going live

Connect your own WhatsApp number, then route it the same way: Numbers → your number → Routing → Webhook. On your own numbers you can also do it from code, and route individual conversations:

// Every conversation on the number
await wassist.phoneNumbers.subscribe("447700900100", { webhookId, applyToExisting: true });

// Or a single conversation, e.g. hand one customer to your code
await wassist.conversations.subscribe(conversationId, { webhookId });

See Conversation routing for per-conversation overrides, lifecycle events and the 24-hour window events.

Introduction

Get Started

Advanced

Hello world: webhook routing

1. Get an API key

2. Write the handler

3. Expose it over HTTPS

4. Create the webhook

5. Route the sandbox to your webhook

6. Say hi

What your endpoint receives

Make it an agent

Using Vercel eve

Going live

Next steps

Managed agent

Conversation routing

​1. Get an API key

​2. Write the handler

​3. Expose it over HTTPS

​4. Create the webhook

​5. Route the sandbox to your webhook

​6. Say hi

​What your endpoint receives

​Make it an agent

​Using Vercel eve

​Going live

​Next steps

Managed agent

Conversation routing

1. Get an API key

2. Write the handler

3. Expose it over HTTPS

4. Create the webhook

5. Route the sandbox to your webhook

6. Say hi

What your endpoint receives

Make it an agent

Using Vercel eve

Going live

Next steps