8000 elevenlabs/post-call-transcripts: post-call transcripts through Hookdeck with a live topology pane and a shared scene kit by leggetter · Pull Request #47 · hookdeck/hookdeck-demos · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
4ad7975
Add ElevenLabs post-call transcripts demo
leggetter Nov 11, 2026
255cb8f
ElevenLabs demo: adopt shared Hookdeck helpers, set source auth via t…
leggetter Nov 12, 2026
c0393bb
ElevenLabs demo: speak first in npm run call, probe trusts the reques…
leggetter Nov 12, 2026
c9ed42a
elevenlabs/post-call-transcripts: inline retry control lined up with …
leggetter Nov 12, 2026
f6ff21f
elevenlabs/post-call-transcripts: add the shared data-flow drawer and…
leggetter Nov 12, 2026
4389aea
elevenlabs/post-call-transcripts: drawer shows the 200 a rejected req…
leggetter Nov 12, 2026
ddc9a94
elevenlabs/post-call-transcripts: setup creates a dedicated demo agen…
leggetter Nov 12, 2026
e61c4cd
_shared/scenes: add the animated-topology scene kit (live driver, scr…
leggetter Nov 12, 2026
2906990
elevenlabs/post-call-transcripts: live topology view, scripted scenes…
leggetter Nov 12, 2026
6fd79b0
elevenlabs/post-call-transcripts: fix the live topology's idle hint
leggetter Nov 12, 2026
88b44ea
elevenlabs/post-call-transcripts: add the captured topology GIFs (lan…
leggetter Nov 12, 2026
a6bd47f
_shared/topology-pane: add the bottom pane for the live topology (tab…
leggetter Nov 12, 2026
3a644f0
elevenlabs/post-call-transcripts: move the live topology into a botto…
leggetter Nov 12, 2026
b340b10
elevenlabs/post-call-transcripts: commit MP4 captures (landscape and …
leggetter Nov 12, 2026
e546614
_shared/scenes: type the scene registry with a cast, not a global Win…
leggetter Nov 12, 2026
58e7bbb
_shared/scenes: keep a stopped packet's label whole; elevenlabs: bad-…
leggetter Nov 16, 2026
ccae480
_shared/scenes: keep a stopped packet's label whole on vertical conne…
leggetter Nov 16, 2026
9ee07ab
elevenlabs/post-call-transcripts: re-capture the MP4s with whole pack…
leggetter Nov 16, 2026
a0a7476
_shared/scenes: capture reads its scene ids and brand from the demo's…
leggetter Nov 16, 2026
0c75656
Say Event Gateway verifies, without naming internal layers
leggetter Nov 16, 2026
d771e77
Say Event Gateway verifies, without naming internal layers (flow-draw…
leggetter Nov 16, 2026
a5a83e5
_shared/theme: import the demo-theme hook from the LiveKit branch (8f…
leggetter Nov 17, 2026
0b3452e
elevenlabs/post-call-transcripts: diary slot logic that reads request…
leggetter Nov 17, 2026
06af18c
elevenlabs/post-call-transcripts: focused layout (explanations behind…
leggetter Nov 17, 2026
2925f33
elevenlabs/post-call-transcripts: plain hero titles that name the sce…
leggetter Nov 18, 2026
4233440
elevenlabs/post-call-transcripts: diary never reads a day of the mont…
leggetter Nov 18, 2026
fbe406b
elevenlabs/post-call-transcripts: check and coerce event fields on wr…
leggetter Nov 18, 2026
195d877
elevenlabs/post-call-transcripts: bind to 127.0.0.1, reject foreign H…
leggetter Nov 18, 2026
19e706a
_shared: skip key redaction when the key is empty, show Verified only…
leggetter Nov 18, 2026
e87a810
elevenlabs/post-call-transcripts: merge readiness: root README shared…
leggetter Nov 18, 2026
4f25387
Merge remote-tracking branch 'origin/main' into feat/elevenlabs-post-…
leggetter Nov 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ stripe/ Stripe integration demos
shopify/ Shopify integration demos
deepgram/ Deepgram integration demos
vapi/ Vapi integration demos
elevenlabs/ ElevenLabs integration demos
_shared/ Source of truth for code shared across demos
```

Expand Down Expand Up @@ -75,6 +76,12 @@ For example, `npx giget@latest gh:hookdeck/hookdeck-demos/deepgram/stt-tts my-de
|------|-------------|
| [agency-routing](vapi/agency-routing/) | A voice AI agency routes each client's Vapi call events to that client's endpoint, with an async tool that returns its result into the live call |

### ElevenLabs

| Demo | Description |
|------|-------------|
| [post-call-transcripts](elevenlabs/post-call-transcripts/) | ElevenLabs Agents post-call webhooks through Hookdeck: signature verification, deduplication on `conversation_id`, retries and replay, and large transcript and audio payloads, stored and shown in a small app |

## Shared Utilities

| Utility | Description |
Expand Down
9 changes: 9 additions & 0 deletions _shared/manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,15 @@
"scenes": "scenes/kit",
"topology-pane": "public/topology-pane",
"theme": "public/theme.js"
},
"elevenlabs/post-call-transcripts": {
"ds": "public/ds",
"hookdeck-cli": "scripts/hookdeck-cli.ts",
"hookdeck-listen": "scripts/hookdeck-listen.ts",
"flow-drawer-server": "src/flow-drawer-server.ts",
"scenes": "scenes/kit",
"topology-pane": "public/topology-pane",
"theme": "public/theme.js"
}
}
}
36 changes: 36 additions & 0 deletions elevenlabs/post-call-transcripts/.env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# ElevenLabs API key (REQUIRED)
# ElevenLabs dashboard: profile menu -> API keys (https://elevenlabs.io/app/settings/api-keys).
# Needs access to ElevenAgents (read and write), Webhooks and Workspace settings.
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here

# ID of the demo agent. Written by `npm run setup`, which creates and configures a dedicated
# agent named "Hookdeck demo: post-call transcripts"; leave it empty.
ELEVENLABS_AGENT_ID=

# Hookdeck project API key (REQUIRED)
# Hookdeck dashboard: Project settings -> API keys. `npm run setup` creates the
# connection in this project and `npm run listen` forwards its source, using a CLI
# config file of its own, so your interactive `hookdeck login` is untouched.
HOOKDECK_API_KEY=your_hookdeck_api_key_here

# Server port (optional)
PORT=4000

# Address the server binds to (optional). Loopback by default; `hookdeck listen` runs on this machine.
# Set HOST=0.0.0.0 only if you need the app reachable from the network, and list the name or IP
# you browse to in ALLOWED_HOSTS (comma-separated): requests with any other Host header get a 403.
# HOST=127.0.0.1
# ALLOWED_HOSTS=

# Path to a Hookdeck CLI binary (optional; default: the hookdeck-cli npm dependency)
# HOOKDECK_CLI=

# Written by `npm run setup`
# Hookdeck source URL that ElevenLabs sends post-call webhooks to
ELEVENLABS_WEBHOOK_URL=
# Signing secret of the ElevenLabs workspace webhook (also set on the Hookdeck source).
# Hookdeck verifies the ElevenLabs-Signature with it; the app only uses it to show the
# result of the SDK's constructEvent next to each delivery.
ELEVENLABS_WEBHOOK_SECRET=
# ID of the ElevenLabs workspace webhook
ELEVENLABS_WEBHOOK_ID=
43 changes: 43 additions & 0 deletions elevenlabs/post-call-transcripts/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Dependencies
node_modules/
package-lock.json

# Build output
dist/

# Environment files
.env
.env.local
.env.development.local
.env.test.local
.env.production.local

# IDE files
.vscode/
.idea/
*.swp
*.swo

# OS files
.DS_Store
Thumbs.db

# TypeScript
*.tsbuildinfo

# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*

# Conversation data and downloaded audio

# JSON data storage
data/

# Hookdeck CLI config written by the setup and listen scripts
run/
public/scenes/
189 changes: 189 additions & 0 deletions elevenlabs/post-call-transcripts/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,189 @@
# ElevenLabs post-call transcripts with Hookdeck

A voice agent built on [ElevenLabs Agents](https://elevenlabs.io/agents) sends a [post-call webhook](https://elevenlabs.io/docs/eleven-agents/workflows/post-call-webhooks) when a conversation ends and its analysis is done. This demo receives those webhooks through [Hookdeck Event Gateway](https://hookdeck.com/event-gateway) and stores and shows each conversation: transcript, summary, data collection results, evaluation outcome and, optionally, the audio.

```
ElevenLabs agent ──post-call webhook──▶ Hookdeck source (ELEVENLABS) ──▶ hookdeck listen ──▶ this app (localhost:4000)
│ verifies ElevenLabs-Signature
│ deduplicates on type + data.conversation_id
└ retries failed deliveries
```

The demo has three parts: this app, an ElevenLabs agent, and Hookdeck. It shows:

| Feature | Where to look |
|---|---|
| **Signature verification** in Event Gateway with Hookdeck's `ELEVENLABS` source type | `scripts/setup.ts` creates the source and sets the secret |
| **Deduplication** on `body.type` + `body.data.conversation_id` | the `RULES` in `scripts/setup.ts`; `npm run send -- --duplicate` |
| **Retries**: make the app fail, watch Hookdeck retry, then replay | the "Retry demo" card in the UI ("Bad line" in the Salon theme) |
| **Large payloads**: transcripts and base64 MP3 audio | the Size column in the UI; `npm run send -- --large 8` |

## Prerequisites

- Node.js 22 or later
- An [ElevenLabs](https://elevenlabs.io) account and an [ElevenLabs API key](https://elevenlabs.io/app/settings/api-keys) that can read and write agents and workspace webhooks
- A [Hookdeck](https://dashboard.hookdeck.com/signup) project and a project API key (Project settings -> API keys)

## Quick start

1. Install dependencies:

```bash
npm install
```

2. Create `.env` and fill in `ELEVENLABS_API_KEY` and `HOOKDECK_API_KEY`:

```bash
cp .env.example .env
```

You don't need an agent of your own: setup creates a dedicated one and writes its ID to `.env`.

3. Set up Hookdeck and ElevenLabs:

```bash
npm run setup
```

The script is idempotent. It:

- creates a Hookdeck source `elevenlabs-post-call` (type `ELEVENLABS`), a CLI destination `local-elevenlabs` (path `/webhooks/elevenlabs`) and a connection with a deduplication rule and a retry rule
- creates an ElevenLabs workspace webhook (HMAC authentication) that points at the Hookdeck source URL, which returns the signing secret
- sets that secret on the Hookdeck source, so Hookdeck verifies every `ElevenLabs-Signature`
- creates (first run) or updates the agent "Hookdeck demo: post-call transcripts": a greeting, a salon booking prompt, a 10-second turn timeout, three data collection items and a `booking_made` evaluation criterion. Your other agents are not touched
- attaches the webhook to that agent for the transcript, audio and `call_initiation_failure` events
- writes `ELEVENLABS_WEBHOOK_URL`, `ELEVENLABS_WEBHOOK_SECRET` and `ELEVENLABS_WEBHOOK_ID` to `.env`

4. In one terminal, forward the source to the app:

```bash
npm run listen
```

5. In another, start the app and open <http://localhost:4000>:

```bash
npm start
```

6. Make a call. Either start a test call from the agent's page in the ElevenLabs dashboard, or hold a text-only conversation from the terminal:

```bash
npm run call
```

A few seconds after the call ends, the transcript appears in the app.

The app listens on `127.0.0.1` only, which is enough because `hookdeck listen` runs on the same machine. It answers `403` to a request whose `Host` header is not `localhost`, `127.0.0.1` or `[::1]`, and the page's state-changing requests carry an `x-demo` header. To reach the app from another device, set `HOST=0.0.0.0` and `ALLOWED_HOSTS=<the name or IP you browse to>` in `.env`. It keeps the 50 most recent conversations.

### Set up ElevenLabs by hand

`npm run setup` calls the ElevenLabs API for you. To do the ElevenLabs part in the dashboard, first create the Hookdeck source (type **ElevenLabs**) and a connection to a CLI destination with path `/webhooks/elevenlabs` in the Hookdeck dashboard, copy the source URL into `ELEVENLABS_WEBHOOK_URL` in `.env`, then:

1. Create a workspace webhook with HMAC authentication and the Hookdeck source URL, following the [ElevenLabs webhook documentation](https://elevenlabs.io/docs/eleven-agents/workflows/post-call-webhooks). Copy the signing secret when it is shown.
2. Paste the secret into the Hookdeck source's **Webhook Signing Secret**.
3. In the agent's **Settings**, under **Post-call webhooks**, select the webhook and choose the events.

## What you'll see

- **Data flow pane** (bottom of the page, open by default; the header collapses it): the live topology of ElevenLabs agent, Event Gateway (with its verify, store, dedup and retry capabilities), `hookdeck listen` and this app, with a packet moving along each edge as a real webhook arrives, and status badges (`answering 500`, `handled · attempt 2`, `duplicate · dropped`). The 3.5 MB audio webhook is drawn thicker and slower than the transcript. Click a node or a packet to fill the detail strip with that webhook: verified or rejected and what ElevenLabs got back, each delivery attempt's status, latency and retry gap, what the app answered, and a **View in Hookdeck** link to the request or event in the dashboard. The other tabs play four scripted scenes of the same topology with captions (Back, Next, Replay): delivery, a duplicate dropped, a bad signature, and the app down with a retry that succeeds. On a phone the pane opens at 60% of the screen height with the portrait layout, and the page keeps that much padding at the bottom so the buttons above stay reachable. It reads Event Gateway with `HOOKDECK_API_KEY` on the server.
- **Who is who**: you are the customer ringing the Hookdeck Hair booking line; the booking assistant is the agent that `npm run setup` creates (its prompt is `AGENT_CONFIG` in `scripts/setup.ts`).
- **Diary**: a week view above the conversations. A conversation whose `booking_made` evaluation is `success` fills a slot from `caller_name`, `requested_service` and `requested_time`. The page works this out from the stored conversations (`public/diary.js`); the webhook handler is unchanged. A `requested_time` it cannot read as a day and a time of day goes in an Unscheduled row as received.
- **Themes**: Salon (the default, the Hookdeck Hair booking line), Light, Dark and System, from the switch at the top right. Salon is `public/theme-salon.css` and `public/theme-salon.copy.js`; the Data flow pane keeps the standard look. Explanations sit behind the ⓘ buttons and hover tips.
- **Deliveries received** (collapsed): the latest requests the app received, with body size and result, and the result of the ElevenLabs SDK's `constructEvent` on the forwarded requests.

Data collection results and evaluation criteria are configured per agent (agent -> **Analysis**). Setup gives the demo agent `caller_name`, `requested_service` and `requested_time` as data collection items and `booking_made` as an evaluation criterion; they show up in the conversation detail.

## Deduplication

ElevenLabs sends three kinds of events with the same `data.conversation_id`: `post_call_transcription`, `post_call_audio` and `call_initiation_failure`. Deduplicating on `conversation_id` alone would drop the audio event after the transcription arrived, so the rule keys on `body.type` and `body.data.conversation_id`:

```json
{ "type": "deduplicate", "window": 3600000, "include_fields": ["body.type", "body.data.conversation_id"] }
```

The rule uses specific fields because a re-delivery carries a new `ElevenLabs-Signature` timestamp and signature, so comparing the whole request would see it as different. The window is the longest Hookdeck allows, one hour.

To see it work without a call:

```bash
npm run send -- --duplicate
```

This sends the same signed transcription twice. Hookdeck accepts both requests, delivers one event and ignores the other. The app also records each `type:conversation_id` it has processed and answers a repeat with `200 duplicate`, so a duplicate that outlives the dedup window (or arrives on a replay) is still stored once.

## Retries and replay

1. In the UI, under **Retry demo**, set **Fail the next** to `1` deliveries and click **Apply**.
2. Make a call (or run `npm run send`).
3. The first delivery attempt gets a `500`. In the Hookdeck dashboard the event shows a failed attempt, and Hookdeck retries it on the connection's retry rule (linear, every 10 seconds, up to 5 times). The next attempt succeeds and the conversation appears.
4. Fail more attempts than the retry rule allows, then open the event in the Hookdeck dashboard and click **Retry** to replay it.

Each attempt shows up in the deliveries table, so you can see the failure and the retry side by side.

## Large payloads

A `post_call_transcription` payload grows with the transcript, the analysis and the dynamic variables. A `post_call_audio` payload carries the whole call as a base64 MP3 inside JSON, so it is the large one. The app accepts bodies up to 100 MB, and the deliveries table shows the size of every request. Hookdeck accepts requests up to your organization's [maximum payload size](https://hookdeck.com/docs/limits).

`npm run send -- --large 8` sends a transcription padded to about 8 MB so you can see how a large body flows through the source, `hookdeck listen` and the app.

## Verifying the signature

Hookdeck verifies `ElevenLabs-Signature` at the source URL, so the app does not have to. Hookdeck forwards the original headers and the original body, so the signature header still reaches the app. When `ELEVENLABS_WEBHOOK_SECRET` is set, the app runs `elevenlabs.webhooks.constructEvent` from [`@elevenlabs/elevenlabs-js`](https://www.npmjs.com/package/@elevenlabs/elevenlabs-js) on each forwarded request and shows the result in the **SDK check** column. It does not block anything.

The SDK rejects a timestamp older than 30 minutes, so a replay of an old event shows a tolerance error in that column while the event is still stored.

## Topology scenes, and MP4s of them

The topology is a scene from the shared scene kit (`_shared/scenes/` in the repo, synced into `scenes/kit/`; this demo's scenes are `scenes/post-call.ts`). One scene definition gives three outputs: the live view in the Data flow pane at the bottom of the page, the four scripted scenes (a 1920x1080 layout and a portrait layout for phones, with the same steps and captions, which the hookdeck.com `steppedDiagram` component can embed), and captures.

```bash
npm run build:scenes # bundle the kit and scenes into public/scenes (npm start does this)
npm run capture # MP4 of each scripted scene, 1920x1080, into scenes/captures
ASPECT=square npm run capture # 1080x1080 for social: phone layout and a large numbered caption
THEME=dark npm run capture -- delivery
```

The capture script seeks each scene's timeline frame by frame in headless Chromium, so frames are exact. The output is MP4 only: social platforms take MP4 and convert GIFs themselves, and guides use the interactive diagrams. It needs `ffmpeg`, and Playwright's Chromium (`npx playwright install chromium`) or Google Chrome. The kit's README (`_shared/scenes/README.md`) explains how to write a scene for another demo.

## Tests

```bash
npm test
```

The tests post signed sample payloads (generated in `src/samples.ts`) to the app and check that conversations are stored, merged, deduplicated and acknowledged, that the failure toggle returns a `500` and then recovers, and that the signature header matches the format the ElevenLabs SDK verifies.

## Project structure

```
elevenlabs/post-call-transcripts/
├── .env.example
├── package.json
├── scripts/
│ ├── setup.ts # Hookdeck source, destination, connection, rules + ElevenLabs webhook and agent
│ ├── listen.ts # hookdeck listen for the source
│ ├── call.ts # text-only conversation with the agent
│ ├── send-sample.ts # signed sample payloads, duplicates, large bodies
│ ├── probe.ts # checks that a good signature is accepted and a bad one rejected
│ └── hookdeck-cli.ts # runs the Hookdeck CLI against HOOKDECK_API_KEY's project (synced from _shared)
├── scenes/
│ ├── post-call.ts # the topology scene: live, and four scripted scenarios (desktop + phone)
│ ├── entry.ts # what the page's bundle exposes
│ ├── kit/ # shared scene kit, synced from _shared/scenes (don't edit)
│ └── captures/ # MP4s from npm run capture (landscape + square, light)
├── src/
│ ├── server.ts # Express app and API
│ ├── webhook.ts # POST /webhooks/elevenlabs
│ ├── store.ts # JSON-file storage, idempotency, audio files
│ ├── events.ts # event and record types
│ └── samples.ts # sample payloads and signer
├── public/ # UI
└── test/
```

## Troubleshooting

- **No webhook arrives**: check that `npm run listen` is running and that the agent's **Post-call webhooks** setting selects the webhook. The Hookdeck dashboard shows the request under the `elevenlabs-post-call` source.
- **A request is rejected with `VERIFICATION_FAILED`**: the signing secret on the Hookdeck source doesn't match the ElevenLabs webhook's. Run `npm run setup` again after deleting the webhook in ElevenLabs, or paste the correct secret into the source.
41 changes: 41 additions & 0 deletions elevenlabs/post-call-transcripts/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
{
"name": "hookdeck-elevenlabs-post-call-transcripts",
"version": "1.0.0",
"private": true,
"description": "ElevenLabs post-call webhooks through Hookdeck: store and browse conversation transcripts, analysis and audio",
"engines": {
"node": ">=22"
},
"scripts": {
"build:scenes": "node scripts/build-scenes.mjs",
"start": "npm run build:scenes && ts-node src/server.ts",
"dev": "npm run build:scenes && ts-node src/server.ts",
"setup": "ts-node scripts/setup.ts",
"listen": "ts-node scripts/listen.ts",
"call": "ts-node scripts/call.ts",
"send": "ts-node scripts/send-sample.ts",
"typecheck": "tsc --noEmit",
"probe": "ts-node scripts/probe.ts",
"test": "node --require ts-node/register --test test/*.test.ts",
"capture": "ts-node scenes/kit/capture/capture.ts"
},
"license": "ISC",
"dependencies": {
"@elevenlabs/elevenlabs-js": "^2.77.0",
"dotenv": "^16.3.1",
"express": "^4.18.2",
"hookdeck-cli": "3.1.0",
"ts-node": "^10.9.2",
"typescript": "^5.9.2",
"ws": "^8.18.0"
},
"devDependencies": {
"@material-symbols/svg-400": "0.47.4",
"@types/express": "^4.17.21",
"@types/node": "^22.0.0",
"@types/ws": "^8.5.12",
"esbuild": "0.25.9",
"gsap": "3.15.0",
"playwright": "1.55.0"
}
}
Loading
Loading
0