Webhooks empfangen und prüfen
Mit einem Webhook erfährt Ihr Programm sofort, wenn etwas passiert ist. SpeakKI sendet dann eine POST-Anfrage mit JSON an Ihre Adresse. Sie müssen nichts abfragen.
Einrichten
Abschnitt betitelt „Einrichten“Der Webhook gehört zu einem Assistenten. Öffnen Sie den Assistenten, wählen Sie die Stufe Feinjustierung und klicken Sie in der Kachel Was er für Anrufer erledigt auf Ändern. Unter Daten an Ihr System senden (Webhook) tragen Sie die Adresse Ihres Programms ein. Dort sehen Sie auch das Secret, mit dem SpeakKI jede Nachricht signiert. Es beginnt mit whsec_. Eine Übersicht aller Webhooks steht unter KI einstellen › Verbindungen › Webhooks & API.
- Die Adresse muss öffentlich erreichbar sein und mit
https://beginnen. - Der Webhook sendet nur, wenn er eingeschaltet und der Assistent veröffentlicht ist.
- Mit Testereignis senden schickt SpeakKI ein Beispiel für
call.endedmit"test": true.
Ereignisse
Abschnitt betitelt „Ereignisse“| Ereignis | Wann | Inhalt |
|---|---|---|
call.ended |
nach jedem geführten Gespräch, eingehend und ausgehend | Gespräch mit Zusammenfassung, erfassten Angaben und Transkript |
outbound_call.finished |
einmal je ausgehendem Anruf, sobald er abgeschlossen ist | der Anruf wie in GET /v1/calls/{id} |
outbound_campaign.finished |
einmal je Kampagne, sobald sie abgeschlossen oder abgebrochen ist | die Kampagne wie in GET /v1/campaigns/{id} |
Alle Felder der drei Ereignisse stehen in der API-Referenz: call.ended, outbound_call.finished und outbound_campaign.finished.
Jede Anfrage trägt diese Header:
| Header | Inhalt |
|---|---|
Speakki-Event |
Name des Ereignisses |
Speakki-Delivery-Id |
ID der Zustellung. Sie bleibt bei Wiederholungen gleich. |
Speakki-Signature |
Zeitstempel und Signatur, siehe Signatur prüfen |
outbound_call.finished
Abschnitt betitelt „outbound_call.finished“Das Ereignis kommt, sobald ein Anruf abgeschlossen ist: completed, not_reached, blocked oder canceled. Zwischen zwei Versuchen kommt es nicht. data ist das Anruf-Objekt der API, mit Ihren variables und metadata.
{ "event": "outbound_call.finished", "created_at": "2026-11-16T09:00:40.000Z", "data": { "id": "0b1d7c2e-6a0f-4d0b-9a55-2f4f8f1c7e10", "status": "not_reached", "block_reason": null, "to": "+4915228817386", "from": "+493023125010", "assistant_id": "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44", "campaign_id": null, "variables": { "name": "Frau Meier" }, "metadata": { "kundennummer": "4711" }, "scheduled_at": null, "next_attempt_at": null, "max_attempts": 1, "attempt_count": 1, "last_result": "no_answer", "created_at": "2026-11-16T09:00:00.000Z", "finished_at": "2026-11-16T09:00:40.000Z", "attempts": [ { "number": 1, "result": "no_answer", "started_at": "2026-11-16T09:00:02.000Z", "ended_at": "2026-11-16T09:00:40.000Z", "duration_seconds": null } ] }}Kam ein Gespräch zustande, sendet SpeakKI zusätzlich call.ended. Dort steht die ID des Anrufs in call.outboundCallId.
outbound_campaign.finished
Abschnitt betitelt „outbound_campaign.finished“Das Ereignis kommt, sobald eine Kampagne completed oder canceled ist. data ist das Kampagnen-Objekt der API. Die Empfänger stehen nicht in der Nachricht, Sie rufen sie über GET /v1/campaigns/{id}/recipients ab. Jeder Anruf der Kampagne löst weiter sein eigenes outbound_call.finished aus.
{ "event": "outbound_campaign.finished", "created_at": "2026-11-16T11:00:00.000Z", "data": { "id": "3f8a2b1c-9d4e-4a6f-8b2c-1e5d7f9a0b3c", "name": "Terminerinnerung November", "status": "completed", "assistant_id": "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44", "from_number_id": null, "from_number": "+493023125010", "contact_list_id": null, "variables": ["name", "termin"], "missing_variables": [], "start_at": null, "call_window": { "days": [1, 2, 3, 4, 5], "from": "09:00", "to": "17:00" }, "pause_seconds": 30, "max_attempts": 2, "retry_delay_minutes": 120, "contact_source": "Bestandskunden mit Einwilligung aus dem Kundenportal", "consent_confirmed_at": "2026-11-16T08:55:00.000Z", "next_dispatch_at": null, "started_at": "2026-11-16T08:55:00.000Z", "completed_at": "2026-11-16T11:00:00.000Z", "created_at": "2026-11-16T08:50:00.000Z", "counts": { "total": 120, "pending": 0, "queued": 0, "reached": 98, "not_reached": 17, "skipped": 5 } }}call.ended
Abschnitt betitelt „call.ended“Das Ereignis kommt nach jedem geführten Telefongespräch. Es ist älter als die API und hat ein eigenes Format: Feldnamen in camelCase, direction in Großbuchstaben.
{ "version": 1, "event": "call.ended", "deliveryId": "6f1c2a9e-3b7d-4e5f-8a1c-9d2e4b6f8a13", "occurredAt": "2026-11-16T09:02:15.000Z", "test": false, "organization": { "id": "b7e4d1c9-2a6f-4b8e-9c3d-5f1a7e9b2c46", "name": "Mustermann Haustechnik" }, "agent": { "id": "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44", "name": "Terminerinnerung" }, "call": { "interactionId": "c1a7e3f9-2b4d-4c6e-9f8a-0d3b5e7a9c21", "callId": "d8b2f4a6-1c3e-4d5f-9a7b-2e4c6f8a1b35", "direction": "OUTBOUND", "outboundCallId": "0b1d7c2e-6a0f-4d0b-9a55-2f4f8f1c7e10", "startedAt": "2026-11-16T09:00:02.000Z", "endedAt": "2026-11-16T09:02:10.000Z", "durationSec": 128, "callerName": "Frau Meier", "callerPhone": "+4915228817386", "status": "OPEN", "category": { "slug": "REQUEST_RECORDED", "label": "Anliegen aufgenommen" }, "summary": "Frau Meier kann am Dienstag nicht und bittet um einen neuen Termin.", "dashboardUrl": "https://app.speakki.de/inbox/c1a7e3f9-2b4d-4c6e-9f8a-0d3b5e7a9c21" }, "contact": { "id": "a4d2c8e6-5f1b-4a3d-8c7e-9b0f2d4a6c81", "name": "Frau Meier", "company": null, "phone": "+4915228817386", "email": null }, "outcomes": [], "capturedData": [], "transcript": null}call.interactionIdist die ID des Gesprächs, dieselbe wieidinGET /v1/conversations/{id}.call.outboundCallIdist bei einem ausgehenden Anruf die ID ausGET /v1/calls/{id}, sonstnull.capturedDataenthält die erfassten Angaben, je EintragtoolName,label,caseKey,caseName,incomplete,capturedAtundfields.outcomesnennt, was im Gespräch passiert ist, je Eintragcategory,label,toolName,caseKey,caseNameundoccurredAt.transcriptist nur gefüllt, wenn für das Gespräch die Anrufaufzeichnung eingeschaltet war, sonstnull. Je Eintragrole,contentundtimestamp.
Signatur prüfen
Abschnitt betitelt „Signatur prüfen“Prüfen Sie bei jeder Nachricht, dass sie wirklich von SpeakKI kommt. Der Header Speakki-Signature hat diese Form:
Speakki-Signature: t=1763283640,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdt ist der Zeitpunkt in Sekunden seit 1970. v1 ist ein HMAC-SHA256 über t, einen Punkt und den rohen Body, gebildet mit Ihrem Secret und hexadezimal geschrieben.
So prüfen Sie:
- Lesen Sie den Body als rohen Text, bevor ein JSON-Parser ihn verändert.
- Berechnen Sie den HMAC-SHA256 über
"<t>.<Body>"mit Ihrem Secret. - Vergleichen Sie das Ergebnis mit
v1, in konstanter Zeit. - Verwerfen Sie Nachrichten, deren
tälter als fünf Minuten ist.
import crypto from "node:crypto";import express from "express";
const SECRET = process.env.SPEAKKI_WEBHOOK_SECRET; // whsec_...
function signaturGueltig(rawBody, header, secret) { const teile = Object.fromEntries( (header ?? "").split(",").map((teil) => { const i = teil.indexOf("="); return [teil.slice(0, i).trim(), teil.slice(i + 1).trim()]; }), ); const t = Number(teile.t); if (!Number.isFinite(t) || !teile.v1) return false; if (Math.abs(Date.now() / 1000 - t) > 300) return false;
const erwartet = crypto .createHmac("sha256", secret) .update(`${t}.${rawBody}`, "utf8") .digest(); const erhalten = Buffer.from(teile.v1, "hex"); return ( erhalten.length === erwartet.length && crypto.timingSafeEqual(erhalten, erwartet) );}
const app = express();
// express.raw liefert den unveränderten Body als Buffer.app.post("/speakki", express.raw({ type: "application/json" }), (req, res) => { const rawBody = req.body.toString("utf8"); if (!signaturGueltig(rawBody, req.get("Speakki-Signature"), SECRET)) { return res.status(401).end(); }
// Sofort bestätigen, danach verarbeiten. res.status(204).end();
const ereignis = JSON.parse(rawBody); if (ereignis.event === "outbound_call.finished") { console.log(ereignis.data.id, ereignis.data.status); }});
app.listen(3000);Dasselbe in Python:
import hashlibimport hmacimport time
def signatur_gueltig(raw_body: bytes, header: str, secret: str) -> bool: teile = dict(teil.strip().split("=", 1) for teil in header.split(",") if "=" in teil) try: t = int(teile["t"]) erhalten = teile["v1"] except (KeyError, ValueError): return False if abs(time.time() - t) > 300: return False erwartet = hmac.new( secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(erwartet, erhalten)Zustellung und Wiederholungen
Abschnitt betitelt „Zustellung und Wiederholungen“- Antworten Sie innerhalb von 15 Sekunden mit einem Status
2xx. Verarbeiten Sie die Nachricht erst danach. - Bei einem Netzwerkfehler, einer Zeitüberschreitung oder den Status
408,425,429und5xxversucht SpeakKI es erneut: bis zu 10 Versuche mit wachsendem Abstand, über etwa 4 Stunden. - Bei anderen
4xx-Antworten und bei Weiterleitungen gibt es keinen weiteren Versuch. SpeakKI folgt keinen Weiterleitungen. Der Fehler steht danach im Dashboard am Webhook. - Dieselbe Nachricht kann mehrfach ankommen. Merken Sie sich die
Speakki-Delivery-Idund verarbeiten Sie jede nur einmal. - Die Reihenfolge ist nicht garantiert.
call.endedkann vor oder nachoutbound_call.finishedeintreffen. - Geht eine Nachricht verloren, holen Sie den Stand über die API nach, zum Beispiel mit
GET /v1/calls/{id}.