Webhooks Overview

Subscribe to real-time event notifications for calls, conversations, AI executions, and campaigns

Webhooks API

The Webhooks API enables you to register HTTPS listener endpoints that receive real-time JSON payloads whenever asynchronous business events occur within Sayvy AI. Receive instant alerts when phone calls complete, AI tools execute, WhatsApp messages arrive or fail, or campaigns terminate.

+-------------------------------------------------------------+
|                      Sayvy AI Event Engine                  |
|                                                             |
|  +--------------------+  +--------------------+  +--------+ |
|  | Voice AI Telephony |  | WhatsApp Broadcast |  | Inbox  | |
|  |   (call.completed) |  | (campaign.started) |  | (msg)  | |
|  +---------+----------+  +---------+----------+  +----+---+ |
|             \                      |                 /      |
|              +---------------------+----------------+       |
|                                    |                        |
|                                    v                        |
|                     +-----------------------------+         |
|                     |     Webhook Dispatcher      |         |
|                     |  (HMAC SHA-256 Signatures)  |         |
|                     +--------------+--------------+         |
|                                    |                        |
|                                    v                        |
|                     +-----------------------------+         |
|                     |   Your Server HTTPS URL     |         |
|                     | (e.g. /api/webhooks/sayvy)  |         |
|                     +-----------------------------+         |
+-------------------------------------------------------------+

---

Event Catalog

Sayvy AI supports 19 granular event types:

Telephony & Calls

Event Name	Trigger Description
call.started	Customer or agent picked up the phone call and audio streaming initiated.
call.completed	Call terminated. Contains duration, end reason, transcript summary, and cost.

Messaging & Conversations

Event Name	Trigger Description
message.received	Inbound customer message received via WhatsApp or SMS.
message.sent	Message dispatched to recipient handset.
message.failed	Message delivery failed or was rejected by upstream carrier.
conversation.started	New conversational thread created in the team inbox.
conversation.closed	Conversation marked closed or resolved by agent or automation.

Leads & Support Tickets

Event Name	Trigger Description
lead.created	New prospective lead extracted during voice call or chat interaction.
lead.updated	Lead profile, status, or intent score changed.
ticket.created	Support ticket generated from customer interaction.
ticket.assigned	Ticket assigned to an internal human agent.
ticket.resolved	Support ticket marked resolved.

AI Agent Execution

Event Name	Trigger Description
ai.reply.generated	Autonomous Voice or chat LLM synthesized a reply.
ai.tool.executed	Voice agent invoked a custom REST API or MCP tool mid-conversation.
agent.handoff	AI transferred conversation to a human live agent.

Outbound Campaigns

Event Name	Trigger Description
campaign.started	Batch campaign began dispatching to contacts.
campaign.completed	All contacts in a campaign reached terminal delivery state.
campaign.message.delivered	Broadcast message confirmed delivered to contact device.
campaign.message.failed	Broadcast message delivery failed for specific contact.

---

Verifying Signatures

To ensure payloads originate from Sayvy AI and have not been tampered with in transit, every delivery request includes an X-Sayvy-Signature header computed using HMAC SHA-256 with your webhook secret:

Python

import hmac
import hashlib

def verify_webhook(payload_bytes: bytes, signature_header: str, secret: str) -> bool:
    """Validate X-Sayvy-Signature against the raw request body bytes."""
    expected_sig = hmac.new(
        secret.encode("utf-8"),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected_sig}", signature_header)

JavaScript

import crypto from "crypto";

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expectedSig = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expectedSig}`),
    Buffer.from(signatureHeader)
  );
}

---

Available Endpoints

Method	Endpoint	Description
POST	/api/v1/webhooks	Register a new webhook subscription
GET	/api/v1/webhooks	List all webhook subscriptions for your organization
GET	/api/v1/webhooks/{webhook_id}	Retrieve details and events for a webhook
PUT	/api/v1/webhooks/{webhook_id}	Update webhook URL, active events, or status
DELETE	/api/v1/webhooks/{webhook_id}	Permanently deregister a webhook subscription

---

‹ Previous

Create webhook

POST /api/v1/webhooks

Next ›