Voice agent webhooks

What you get

A voice platform tells you a call completed. It cannot tell you the agent said the problem was solved and the customer immediately said it was not. That is what this adds: each call comes back with a sentiment trajectory across turns, a false-resolution check, and a review status you can queue on.

Step 1 — Create the endpoint

In your voice platform, create a post-call webhook and copy the signing secret it shows you. Then register it with Nyeti:

curl -X POST https://api.nyeti.ai/v1/webhooks \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "wsec_the_secret_from_your_platform",
    "description": "Support line"
  }'

The response contains the URL to paste back:

{
  "id": "b2f1...",
  "slug": "9f8c3a1d4e7b2c5f8a1d4e7b2c5f8a1d",
  "receiver_url": "https://api.nyeti.ai/v1/webhooks/9f8c3a1d4e7b2c5f8a1d4e7b2c5f8a1d",
  "provider": "elevenlabs",
  "active": true
}

Step 2 — Paste the URL back

Set receiver_url as the post-call webhook URL in your voice platform. That is the whole setup. Calls start appearing under Conversations as they complete.

What comes back

Each accepted call returns a summary. Note that provider_verdict is what your voice platform concluded and review_status is what we concluded. They can disagree, and the disagreement is usually the interesting part.

{
  "status": "processed",
  "conversation_id": "conv_9f2b41",
  "turns_received": 6,
  "turns_analysed": 6,
  "review_status": "needs_review",
  "suggested_action": "handoff",
  "false_resolution": true,
  "sentiment_trend": {
    "direction": "deteriorating",
    "opened_at_valence": 0,
    "current_valence": -1,
    "negative_streak": 3,
    "summary": "The customer has been negative for 3 consecutive messages without improving."
  },
  "provider_verdict": "success"
}

Security

• Every request must be signed with your webhook secret. Unsigned or incorrectly signed requests are rejected, even with a correct URL.
• Signatures older than 30 minutes are rejected, so a captured request cannot be replayed later.
• The URL contains a random identifier rather than your account name, so it reveals nothing about you if it is seen.
• Your signing secret is stored for verification and is never shown again after setup.

Retries and repeated conversation IDs

Voice platforms retry failed deliveries. A retry sends the same call again, so we acknowledge it and do nothing. Retries never double-count a call or bill you twice. If we fail to process a call we return an error on purpose, so your platform retries and the conversation is not lost.

Some platforms reuse a conversation ID when a customer calls back, or recycle IDs over time. When we receive a new call under an ID we have seen before, we keep it as a separate segment of that ID rather than discarding it or merging it into the earlier call. Each segment is analysed on its own, so a calm follow-up is never coloured by an earlier frustrated call. The response tells you which segment was created.

Managing endpoints

• GET /v1/webhooks — list your endpoints and recent deliveries.
• PATCH /v1/webhooks?id=<id> — set active to false to pause an endpoint without losing its history.

Which events are used

Transcript events are analyzed. Audio-only and failed-call events are accepted and ignored, since neither contains a conversation to analyze. Nothing needs configuring for this.