Webhooks

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 endpoints

Talkturo sends and receives webhooks for billing events, carrier compliance updates, flow triggers, and integration events from third-party providers. Use this reference to identify each endpoint, understand how requests are authenticated, and verify the shape of the key request and response data.

Webhook endpoint summary

Billing webhooks

POST /api/billing/webhook receives Stripe events for checkout completion, subscription lifecycle changes, invoices, and successful payment intents. Talkturo verifies the stripe-signature header using STRIPE_WEBHOOK_SECRET before processing the event.

Headers

Stripe event types

Response fields

Carrier webhooks

Carrier webhooks update phone-number compliance and bundle state. Telnyx and Twilio use different trust models, so configure each endpoint according to the provider.

Telnyx compliance webhook

POST /api/phone-numbers/telnyx-webhook receives Telnyx KYC status events. The endpoint verifies the ED25519 signature using TELNYX_PUBLIC_KEY, requires access to the raw request body, and returns 200 after processing to avoid unnecessary retries.

Response fields

Twilio bundle webhook

POST /api/phone-numbers/twilio-webhook receives Twilio bundle status callbacks. The endpoint does not authenticate the inbound request directly. Instead, it reads the bundle identifier from the payload and re-fetches the current status from Twilio before applying updates.

Request fields

Response fields

Flow trigger webhooks

POST /api/flow/[flowId]/trigger triggers a published flow from an external system or a voice agent. The endpoint verifies an SHA-256 HMAC of the raw request body using the flow version trigger_secret, passed in the X-Talkturo-Secret header.

Path parameters

Headers

Query parameters

Request body

Response fields

Integration provider webhooks

POST /api/flow/integrations/webhooks/[provider] receives inbound events from supported providers and routes them into Talkturo flow integrations. Each webhook uses its own HMAC secret.

Path parameters

Headers

Response behavior

The endpoint validates the provider-specific secret, parses the event payload, and dispatches the event into the configured integration flow. Response payloads depend on the integration and event path, but authentication failure prevents processing.

Meta and Facebook webhooks

GET /api/flow/integrations/webhooks/meta supports webhook verification, and POST /api/flow/integrations/webhooks/meta receives lead ads events. Talkturo authenticates requests with an HMAC derived from META_APP_SECRET.

Request methods

Headers

Response behavior

On verification requests, Talkturo returns the challenge value when validation succeeds. On event delivery requests, Talkturo validates the payload and processes inbound Meta or Facebook lead data.

Assistant webhook testing

POST /api/assistants/[assistantId]/webhooks/test sends a test webhook delivery for an assistant configuration. Use this endpoint to confirm that your target URL, headers, and downstream receiver behave as expected before enabling production delivery.

Path parameters

Authentication

This endpoint uses session authentication. It is intended for authenticated dashboard users testing assistant webhook delivery, not for third-party providers posting into Talkturo.

LiveKit token handler

GET /auth/token generates a LiveKit access token, creates a room when needed, and dispatches an agent. This endpoint is public and exposed through middleware rather than a standard API route.

Query parameters

Response fields

Zapier integration

POST /api/integrations/zapier is the Talkturo endpoint used by the Zapier integration. Use this endpoint when connecting Talkturo events or actions into Zapier workflows.

Response behavior

The exact payload and authentication behavior depend on the Zapier integration configuration. If you are building against this endpoint, validate the specific integration setup in your workspace before sending production traffic.

Security guidance

The webhook surface in Talkturo falls into three patterns:

• Provider-signed requests for Stripe and Telnyx.
• Talkturo-managed HMAC secrets for flow triggers and integration webhooks.
• State re-verification for callbacks such as Twilio, where Talkturo fetches the current provider state before applying updates.

Related endpoints