Zum Inhalt springen
Hilfe-Center
Support kontaktierenApp öffnen

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.

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.ended mit "test": true.
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

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.

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
}
}
}

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.interactionId ist die ID des Gesprächs, dieselbe wie id in GET /v1/conversations/{id}.
  • call.outboundCallId ist bei einem ausgehenden Anruf die ID aus GET /v1/calls/{id}, sonst null.
  • capturedData enthält die erfassten Angaben, je Eintrag toolName, label, caseKey, caseName, incomplete, capturedAt und fields.
  • outcomes nennt, was im Gespräch passiert ist, je Eintrag category, label, toolName, caseKey, caseName und occurredAt.
  • transcript ist nur gefüllt, wenn für das Gespräch die Anrufaufzeichnung eingeschaltet war, sonst null. Je Eintrag role, content und timestamp.

Prüfen Sie bei jeder Nachricht, dass sie wirklich von SpeakKI kommt. Der Header Speakki-Signature hat diese Form:

Speakki-Signature: t=1763283640,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

t 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:

  1. Lesen Sie den Body als rohen Text, bevor ein JSON-Parser ihn verändert.
  2. Berechnen Sie den HMAC-SHA256 über "<t>.<Body>" mit Ihrem Secret.
  3. Vergleichen Sie das Ergebnis mit v1, in konstanter Zeit.
  4. 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 hashlib
import hmac
import 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)
  • 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, 429 und 5xx versucht 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-Id und verarbeiten Sie jede nur einmal.
  • Die Reihenfolge ist nicht garantiert. call.ended kann vor oder nach outbound_call.finished eintreffen.
  • Geht eine Nachricht verloren, holen Sie den Stand über die API nach, zum Beispiel mit GET /v1/calls/{id}.