Skip to main content
Use the local forwarder while you develop on your laptop, then point the same handler at a webhook subscription when you deploy.

Before you start

  • Node.js 22.22.3 or newer.
  • Chat SDK 4.39.0, its memory state adapter, and Relay’s adapter.
  • An Agent Token and a webhook signing secret for your staging agent.

Connect

On your laptop

The staging CLI includes the signed local forwarder:
The command will read the agent’s WebSocket events and POST each one to your local route with the same signature headers used by a deployed webhook. Set the printed local signing secret as RELAY_WEBHOOK_SECRET while the process runs.

Deployed

Create a webhook subscription whose target is your public HTTPS route, then store its signing secret as RELAY_WEBHOOK_SECRET. Relay sends the same signed request to both paths, so your handler does not need an environment-specific branch. Install the packages from one Chat SDK major version line:
The source is packages/chat-sdk-adapter, with a standalone server example. Create one Chat SDK instance with the Relay adapter and mount POST /webhooks/relay:
Pass the request body unchanged because the signature covers the raw bytes. Use a shared state adapter before running more than one instance.

Send it a message

Open Relay on your phone and message the agent’s Handle. Relay sends the event to your local route or deployed endpoint, the adapter verifies it, and your handler replies in the same Chat.

What it can do

When it fails

  • Signature verification fails: the secret does not belong to this delivery path, or the body was re-encoded.
  • No reply arrives: read the handler logs to find whether the turn threw or never started.
  • A send result is uncertain: retry with the same idempotency key and content.

Next steps