Convo API Docs

Receive real-time event notifications via webhooks. Available to Professional and Enterprise tiers.

Webhooks deliver real-time event notifications to your server. Available to Professional and Enterprise tiers.

Events

Event	Data fields
`conversation.created`	conversationId
`conversation.updated`	conversationId, title
`conversation.keypoints.ready`	conversationId, title
`conversation.summary.ready`	conversationId, title, sectionCount
`conversation.action_items.ready`	conversationId, actionItemCount
`conversation.feedback.ready`	conversationId, overallScore
`conversation.shared`	conversationId, shareUrl
`conversation.deleted`	conversationId
`transcript.ready`	conversationId, segmentCount
`transcript.failed`	conversationId, error
`webhook.test`	message

Payload Format

{
  "event": "conversation.keypoints.ready",
  "data": { "conversationId": "sess_a1b2c3", "title": "Q1 Planning Review" },
  "timestamp": "2026-03-19T14:30:00.000Z"
}

Signature Verification

Payloads are signed with HMAC-SHA256 using the webhook secret. Verify the X-Convo-Signature header. The event type is in the X-Convo-Event header.

const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', webhookSecret)
  .update(rawBody)
  .digest('hex');
const isValid = signature === req.headers['x-convo-signature'];

Delivery Behavior

Webhooks are delivered with a 10-second timeout. Your endpoint must respond within this window.
Delivery is fire-and-forget — failed deliveries are not retried. Design your endpoint to return 200 quickly and process data asynchronously if needed.
To update a webhook's URL or events, delete the existing webhook and create a new one.

Creating a Webhook

const res = await fetch("https://www.itsconvo.com/api/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer convo_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://your-server.com/webhooks/convo",
    events: ["conversation.keypoints.ready", "transcript.ready"],
  }),
});
const { data } = await res.json();
// Store data.secret securely — it's only shown once
console.log(data.secret);

Managing Webhooks

Use the webhook endpoints in the API Reference section to list, test, and delete webhooks. The webhook secret for HMAC verification is returned once on creation — store it securely.