Webhooks
Konfigurieren und empfangen Sie Talkturo-Webhooks für Billing-Events, Carrier-Compliance, Flow-Trigger, Provider-Integrationen und LiveKit-Token-Erzeugung — mit Signaturprüfung und Event-Typ-Referenz.
curl -X POST "https://api.talkturo.com/api/billing/webhook" \
-H "Content-Type: application/json" \
-H "stripe-signature: t=1731544800,v1=3f2f0f3816a9a9f5d9f5f8d91d2b1cc95fb08b19e92d7fbb7ebdf1fd4d6f2ab4" \
-d '{
"id": "evt_1QmYxL2eZvKYlo2C9r81AbCd",
"object": "event",
"type": "checkout.session.completed",
"data": {
"object": {
"id": "cs_test_b1N7x2rM8pQ4sK9t",
"object": "checkout.session",
"customer": "cus_R9h2mK7qX1tL0n",
"payment_status": "paid",
"metadata": {
"account_slug": "acme-sales",
"planId": "credits_1000"
}
}
}
}'
{
"received": true
}
curl -G "https://api.talkturo.com/auth/token" \
--data-urlencode "mode=voice" \
--data-urlencode "room=sales-demo-room" \
--data-urlencode "assistant_id=ast_7c91e4f0" \
--data-urlencode "account_slug=acme-sales" \
--data-urlencode "visitor_name=Jane Chen" \
--data-urlencode "visitor_phone=+14155550182"
{
"identity": "visitor_9f2b6d1c",
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.livekit.token",
"roomName": "sales-demo-room",
"agentName": "Acme Sales Assistant"
}
Webhook-Endpunkte
Talkturo sendet und empfängt Webhooks für Billing-Events, Carrier-Compliance-Updates, Flow-Trigger und Integrations-Events von Drittanbietern. Nutzen Sie diese Referenz, um jeden Endpunkt zu identifizieren, die Authentifizierung der Anfragen zu verstehen und die Form der wichtigsten Anfrage- und Antwortdaten zu prüfen.
Talkturo verwendet je nach Quellsystem unterschiedliche Sicherheitsmodelle für Webhook-Endpunkte. Stripe-Anfragen nutzen Signaturprüfung, Telnyx verwendet ED25519-Signaturen, Flow- und Provider-Webhooks nutzen HMAC-Secrets, und einige Carrier-Callbacks vermeiden Vertrauen in eingehende Payloads, indem der Status erneut beim Provider abgerufen wird.
Webhook-Endpunktübersicht
| Methode | Endpunkt | Zweck | Authentifizierung | Hinweise |
|---|---|---|---|---|
POST | /api/billing/webhook | Stripe-Billing-Events empfangen | stripe-signature verifiziert mit STRIPE_WEBHOOK_SECRET | Gibt immer 200 zurück |
POST | /api/phone-numbers/telnyx-webhook | Telnyx-KYC- und Compliance-Status-Updates empfangen | ED25519-Signatur verifiziert mit TELNYX_PUBLIC_KEY | Gibt 503 zurück, wenn der Schlüssel nicht konfiguriert ist, 400 bei ungültiger Signatur |
POST | /api/phone-numbers/twilio-webhook | Twilio-Bundle-Status-Callbacks empfangen | Keine | Ruft den Status erneut von der Twilio-API ab, statt dem geposteten Status zu vertrauen |
POST | /api/flow/[flowId]/trigger | Veröffentlichten Flow auslösen | HMAC in X-Talkturo-Secret | Unterstützt asynchrone und synchrone Ausführung |
POST | /api/flow/integrations/webhooks/[provider] | Provider-Webhooks empfangen | HMAC-Secret pro Webhook | Unterstützte Provider umfassen Cal.com, Calendly und Slack |
GET / POST | /api/flow/integrations/webhooks/meta | Meta-Lead-Events verifizieren und empfangen | HMAC mit META_APP_SECRET | Verarbeitet Meta- und Facebook-Lead-Ads |
POST | /api/assistants/[assistantId]/webhooks/test | Webhook-Zustellung für einen Assistenten testen | Sitzungsauthentifizierung | Für Zustellungstests, nicht für eingehende Drittanbieter-Webhooks |
GET | /auth/token | LiveKit-Token erzeugen und Agent dispatchen | Keine | Öffentlicher Token-Handler über Middleware |
POST | /api/integrations/zapier | Zapier-Integrationsanfragen empfangen | Endpunktspezifisches Integrationsverhalten | Wird vom Zapier-Integrationsflow verwendet |
Billing-Webhooks
POST /api/billing/webhook empfängt Stripe-Events für abgeschlossene Checkouts, Änderungen im Abo-Lebenszyklus, Rechnungen und erfolgreiche Payment Intents. Talkturo verifiziert den Header stripe-signature mit STRIPE_WEBHOOK_SECRET, bevor das Event verarbeitet wird.
Behandeln Sie eine Anfrage an /api/billing/webhook nicht als vertrauenswürdig, solange die Stripe-Signaturprüfung nicht erfolgreich ist. Die Signaturprüfung schützt den Endpunkt vor gefälschten Billing-Events.
Header
Stripe-Anfragesignatur. Talkturo verifiziert diesen Header mit der Umgebungsvariable STRIPE_WEBHOOK_SECRET.
Stripe-Event-Typen
Antwortfelder
Gibt true zurück, wenn Talkturo die Webhook-Anfrage akzeptiert. Der Endpunkt gibt nach der Verarbeitung der Anfrage immer HTTP 200 zurück.
Carrier-Webhooks
Carrier-Webhooks aktualisieren Compliance- und Bundle-Status von Telefonnummern. Telnyx und Twilio verwenden unterschiedliche Vertrauensmodelle — konfigurieren Sie jeden Endpunkt entsprechend dem Provider.
Telnyx-Compliance-Webhook
POST /api/phone-numbers/telnyx-webhook empfängt Telnyx-KYC-Status-Events. Der Endpunkt verifiziert die ED25519-Signatur mit TELNYX_PUBLIC_KEY, benötigt Zugriff auf den rohen Request-Body und gibt nach der Verarbeitung 200 zurück, um unnötige Retries zu vermeiden.
Wenn TELNYX_PUBLIC_KEY nicht konfiguriert ist, gibt Talkturo 503 zurück. Wenn die Signaturprüfung fehlschlägt, gibt Talkturo 400 zurück.
Antwortfelder
Gibt true zurück, wenn Talkturo die Webhook-Anfrage akzeptiert.
Carrier- oder Requirement-Group-Status, abgeleitet aus dem Telnyx-Event.
Gibt an, ob Talkturo den internen Compliance-Status aktualisiert hat.
Gibt an, ob das Event einer bekannten Compliance-Anfrage oder Requirement Group zugeordnet werden konnte.
Twilio-Bundle-Webhook
POST /api/phone-numbers/twilio-webhook empfängt Twilio-Bundle-Status-Callbacks. Der Endpunkt authentifiziert die eingehende Anfrage nicht direkt. Stattdessen liest er die Bundle-Kennung aus dem Payload und ruft den aktuellen Status erneut von Twilio ab, bevor Updates angewendet werden.
Anfragefelder
Twilio-Bundle-Kennung. Der Endpunkt akzeptiert auch BundleSid und bundle_sid.
Antwortfelder
Gibt true zurück, wenn Talkturo den Callback akzeptiert.
Aktueller Bundle-Status, nachdem Talkturo den Status erneut von Twilio abgerufen hat.
Gibt an, ob der Callback einer nachverfolgten Compliance-Anfrage zugeordnet werden konnte.
Flow-Trigger-Webhooks
POST /api/flow/[flowId]/trigger löst einen veröffentlichten Flow aus einem externen System oder einem Voice-Agenten aus. Der Endpunkt verifiziert einen SHA-256-HMAC des rohen Request-Bodys mit dem trigger_secret der Flow-Version, übergeben im Header X-Talkturo-Secret.
Erzeugen Sie den HMAC aus dem exakten rohen Request-Body. Wenn sich der Body nach dem Signieren ändert, lehnt Talkturo die Anfrage ab.
Pfadparameter
Eindeutige Kennung des auszulösenden Flows.
Header
HMAC-Signatur für den Request-Body. Talkturo validiert diesen Wert gegen das Trigger-Secret der veröffentlichten Flow-Version.
Query-Parameter
Wenn auf true gesetzt, wartet Talkturo bis zu 30 Sekunden auf den Abschluss des Flows und gibt die Ausgabe inline zurück. Wenn weggelassen, führt Talkturo den Flow asynchron aus und gibt eine Run-ID mit HTTP 202 zurück.
Request-Body
Eingabewerte, die zur Laufzeit in den Flow übergeben werden.
Optionaler Ausführungskontext. Der Kontext kann assistentenbezogene Werte wie assistant_id enthalten.
Antwortfelder
Gibt an, ob Talkturo die Trigger-Anfrage angenommen oder abgeschlossen hat.
Eindeutige Kennung für den Flow-Lauf.
Flow-Ausgabe, die nur bei erfolgreicher synchroner Ausführung zurückgegeben wird.
Fehlermeldung bei fehlgeschlagener synchroner Ausführung.
Kennung des Nodes, der während der synchronen Ausführung fehlgeschlagen ist.
Teilweise Ausgabe, die vor dem Fehlschlagen eines synchronen Laufs erfasst wurde.
Integrations-Provider-Webhooks
POST /api/flow/integrations/webhooks/[provider] empfängt eingehende Events von unterstützten Providern und leitet sie in Talkturo-Flow-Integrationen weiter. Jeder Webhook verwendet ein eigenes HMAC-Secret.
Pfadparameter
Provider-Name für den eingehenden Webhook. Unterstützte Provider umfassen cal.com, calendly und slack.
Header
HMAC-Signatur für den Provider-Webhook-Payload. Talkturo validiert den Payload gegen das für diesen Webhook konfigurierte Secret.
Antwortverhalten
Der Endpunkt validiert das providerspezifische Secret, parst den Event-Payload und dispatcht das Event in den konfigurierten Integrationsflow. Antwort-Payloads hängen von Integration und Event-Pfad ab; bei Authentifizierungsfehlern findet keine Verarbeitung statt.
Meta- und Facebook-Webhooks
GET /api/flow/integrations/webhooks/meta unterstützt die Webhook-Verifizierung, und POST /api/flow/integrations/webhooks/meta empfängt Lead-Ads-Events. Talkturo authentifiziert Anfragen mit einem HMAC, der aus META_APP_SECRET abgeleitet wird.
Anfragemethoden
Meta-Verifizierungsmodus bei der Webhook-Registrierung.
Verifizierungstoken-Wert, den Meta während der Endpunktvalidierung sendet.
Challenge-String, den Talkturo bei erfolgreicher Verifizierung zurückgibt.
Header
Üblicher Meta-Signatur-Header zur Validierung des Request-Bodys gegen META_APP_SECRET.
Antwortverhalten
Bei Verifizierungsanfragen gibt Talkturo den Challenge-Wert zurück, wenn die Validierung erfolgreich ist. Bei Event-Zustellungsanfragen validiert Talkturo den Payload und verarbeitet eingehende Meta- oder Facebook-Lead-Daten.
Assistenten-Webhook-Tests
POST /api/assistants/[assistantId]/webhooks/test sendet eine Test-Webhook-Zustellung für eine Assistentenkonfiguration. Nutzen Sie diesen Endpunkt, um zu bestätigen, dass Ziel-URL, Header und Downstream-Empfänger wie erwartet funktionieren, bevor Sie die Produktionszustellung aktivieren.
Pfadparameter
Eindeutige Kennung des Assistenten, dessen Webhook-Konfiguration Sie testen möchten.
Authentifizierung
Dieser Endpunkt verwendet Sitzungsauthentifizierung. Er ist für authentifizierte Dashboard-Benutzer zum Testen der Assistenten-Webhook-Zustellung gedacht, nicht für Drittanbieter, die in Talkturo posten.
LiveKit-Token-Handler
GET /auth/token erzeugt ein LiveKit-Access-Token, erstellt bei Bedarf einen Room und dispatcht einen Agent. Dieser Endpunkt ist öffentlich und wird über Middleware statt über eine Standard-API-Route bereitgestellt.
Query-Parameter
Verbindungsmodus, den der Token-Handler verwendet.
Angeforderter LiveKit-Room-Name.
Assistentenkennung zur Auswahl und zum Dispatch des Agents.
Kontokennung, die der Anfrage zugeordnet ist.
Account-Slug, der der Anfrage zugeordnet ist.
Unternehmenskennung, die dem Besucher oder der Sitzung zugeordnet ist.
Anzeigename des Besuchers, der der LiveKit-Identität zugeordnet ist.
Telefonnummer des Besuchers, die der Sitzung zugeordnet ist.
Optionales Flag für das Billing-Verhalten bei der Token-Erzeugung.
Antwortfelder
Erzeugte Teilnehmeridentität.
LiveKit-Access-Token für die Teilnehmer-Sitzung.
Name des LiveKit-Rooms, der für die Sitzung erstellt oder wiederverwendet wurde.
Name des gedispatchten Agents.
Zapier-Integration
POST /api/integrations/zapier ist der Talkturo-Endpunkt für die Zapier-Integration. Verwenden Sie diesen Endpunkt, wenn Sie Talkturo-Events oder -Aktionen in Zapier-Workflows einbinden.
Antwortverhalten
Exakter Payload und Authentifizierungsverhalten hängen von der Zapier-Integrationskonfiguration ab. Wenn Sie gegen diesen Endpunkt entwickeln, validieren Sie das konkrete Integrationssetup in Ihrem Workspace, bevor Sie Produktionsverkehr senden.
Sicherheitshinweise
Bevorzugen Sie signierte Webhooks, wann immer das Upstream-System sie unterstützt. Bei unsignierten Callbacks behandeln Sie den eingehenden Body als unvertrauenswürdige Eingabe und verifizieren den Status beim Provider, bevor Sie Kontodaten ändern.
Die Webhook-Oberfläche in Talkturo folgt drei Mustern:
- Provider-signierte Anfragen für Stripe und Telnyx.
- Von Talkturo verwaltete HMAC-Secrets für Flow-Trigger und Integrations-Webhooks.
- Status-Reverifizierung für Callbacks wie Twilio, bei denen Talkturo den aktuellen Provider-Status abruft, bevor Updates angewendet werden.