chamade-template-vercel-nextjs — Next.js Starter Template

SHA-256: a78e7905b048f1c60f5ddca7a9fedc87c62938a044c95693e8c139134f1d6bc7

2026-10-14T19:53:24.025Z

# Chamade webhook handler — Vercel starter

Next.js 15 App Router. One API route at `/api/chamade-webhook` that:
1. Verifies the HMAC signature on the raw body
2. Dispatches `dm.received` to Claude (Anthropic SDK)
3. POSTs the model's reply back to Chamade via `/api/reply/dm` with the
   `reply_token` from the event

Reference for the wire format: <https://chamade.io/docs/webhooks>.

## Deploy

**1. Push to your GitHub** (Vercel needs a Git host; Codeberg/GitLab also work):

```bash
cp -r docs/templates/vercel-nextjs ~/my-chamade-handler
cd ~/my-chamade-handler
git init && git add -A && git commit -m "init" && git remote add origin <your-repo> && git push -u origin main
```

**2. Import on Vercel:** New Project → pick the repo → set env vars (next step) → Deploy.

**3. Set env vars** (Vercel project settings or `vercel env`):

| Variable | Required | Notes |
|---|---|---|
| `CHAMADE_WEBHOOK_SECRET` | yes | One-time reveal in `/dashboard/keys` after saving the webhook URL |
| `ANTHROPIC_API_KEY` | yes | <https://console.anthropic.com> |
| `CHAMADE_BASE_URL` | no | Defaults to `https://chamade.io`. Set to `https://dev.chamade.io` to test against dev |
| `ANTHROPIC_MODEL` | no | Defaults to `claude-sonnet-4-6` |

**4. Copy the ALIAS URL** into Chamade dashboard → channel → Webhook → Configure.

> ⚠️ **Use the stable alias, NOT the per-deploy URL.**
>
> The output of `vercel` shows a deploy-specific URL like
> `https://chamade-handler-fw1y8znp6-<scope>.vercel.app`. Don't use that —
> it's a frozen snapshot of one specific deploy. The next time you rotate
> a secret or `vercel env add` a new var, **that URL keeps its original
> env-var snapshot** and Chamade keeps hitting a stale function.
>
> Use the alias instead: `https://<project-name>.vercel.app/api/chamade-webhook`
> (e.g. `https://chamade-handler.vercel.app/api/chamade-webhook`). The alias
> auto-tracks every `vercel --prod` so your env-var rotations are honored.
>
> Check aliases with `npx vercel alias ls`.

**5. Click "Send test" in the dashboard.** You should see HTTP 200 in the delivery log within a couple of seconds.

## What the handler does

- **`dm.received`** → send `event.data.text` to Claude, post the reply to `/api/reply/dm`
- **`agent.timeout`** → async-reply with a default "sorry for the delay" message
- **`webhook.test`** → ack only (verifies signing works end-to-end)
- **everything else** → ack only (extend `app/api/chamade-webhook/route.ts` as you wire voice etc.)

## Customizing

- **System prompt / model behavior**: edit `handleDmReceived` in `app/api/chamade-webhook/route.ts`
- **Memory across messages**: replace the in-memory `SEEN` set with Vercel KV or Upstash Redis; store conversation history keyed by `event.data.conversation_id`
- **Voice (`call.transcript`)**: add a case in the `switch` calling `replyCallSay(event, text)` from `lib/chamade.ts`
- **Idempotency persistence**: the starter uses an in-memory Set keyed by `event_id`. For multi-region Vercel deployments use KV/Redis instead — retries from the same instance dedupe locally, retries that bounce across regions need shared state.

## Local development

```bash
npm install
cp .env.example .env.local
# fill CHAMADE_WEBHOOK_SECRET + ANTHROPIC_API_KEY
npm run dev
# in another terminal, expose with ngrok:
ngrok http 3000
# paste the ngrok URL + /api/chamade-webhook into Chamade dashboard
```

Localhost + `*.ngrok-free.app` are HTTPS-bypassed in Chamade's dispatcher so http://localhost:3000 also works directly if you run Chamade in your own machine.

## Caveats

- Vercel function timeout: Hobby plan caps at 60s, Pro/Enterprise at 300s. Long Claude responses + chained tool use can exceed this — set `maxDuration` in `route.ts` to match your plan
- Cold starts on Vercel can hit 1-2s; if you need consistently sub-second replies, use Vercel Edge Functions (swap `runtime = "nodejs"` to `"edge"` — `crypto` from `node:crypto` is available in the Edge runtime since 2024) or pre-warm with a low-traffic ping schedule
- The signature verifies against `process.env.CHAMADE_WEBHOOK_SECRET` — if you rotate it in the dashboard, deploy the new value too **before** any new event fires, otherwise Chamade retries until DLQ

## License

Pick whatever you ship under — this starter is MIT.