Webhooks

Set a webhookUrl on an agent to get a summary POSTed to your own server after every call it handles — no polling required.

Setting it up

curl -X PATCH https://convostack.ai/api/agents/{id}/draft \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"webhookUrl": "https://example.com/webhooks/convostack"}'

curl -X POST https://convostack.ai/api/agents/{id}/publish \
  -H "Authorization: Bearer cak_live_..."

Like any other agent field, this only takes effect once published. Pass null to disable it.

Payload

Delivered as POST with Content-Type: application/json once the call ends:

{
  "callLogId": "abc123",
  "organizationId": "11111111-2222-3333-4444-555555555555",
  "disposition": "answered",
  "duration": 47,
  "recordingUrl": "https://.../recording.mp3",
  "transcriptSummary": "Caller: Hi, I need help with my order.\nAgent: Sure, what's the order number?...",
  "extractedData": { "orderNumber": "12345" },
  "convostackCallId": "9a1b2c3d-..."
}

Field	Notes
callLogId	The internal call id — identical to convostackCallId below. (A separate, non-public Amazon Connect integration path supports substituting your own reference id here; the public webhookUrl feature documented on this page always sends the call id verbatim.)
disposition	answered, or the call's terminal status if it didn't complete normally
duration	Seconds
recordingUrl	Present only if call recording is enabled
transcriptSummary	A plain-text rendering of the conversation turns
extractedData	Structured data the agent captured during the call (only present if the agent's tools/workflow extracted any)
convostackCallId	The id you'd use to look the call up via GET /api/calls/{id}

Delivery guarantees

• Delivered via a plain HTTPS POST — your endpoint must respond with a 2xx status for delivery to count as successful.
• Up to 3 attempts total (2 retries) with exponential backoff — roughly 2s between attempt 1 and 2, then 4s between attempt 2 and 3 (max span ~6s) — if your endpoint times out, errors, or returns a non-2xx status.
• After 3 failed attempts, delivery is given up — there's no dead-letter queue or manual replay today. If you need to reconcile missed webhooks, poll GET /api/calls as a fallback.
• There's currently no signature/HMAC header on the payload — treat the endpoint URL itself as the shared secret (use an unguessable path, and validate the payload shape before trusting its contents).