Webhooks API

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

+-------------------------------------------------------------+
|                      Pingr 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/pingr)  |         |
|                     +-----------------------------+         |
+-------------------------------------------------------------+

Event Catalog

Pingr 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 Pingr AI and have not been tampered with in transit, every delivery request includes an X-Pingr-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-Pingr-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 ›

Overview

Agents

Campaigns

Contacts

Templates

Knowledge Base

Webhooks

Call Logs

Quick Replies

Inbox

Webhooks Overview

Webhooks API

Event Catalog

Telephony & Calls

Messaging & Conversations

Leads & Support Tickets

AI Agent Execution

Outbound Campaigns

Verifying Signatures

Available Endpoints

​Webhooks API

​Event Catalog

​Telephony & Calls

​Messaging & Conversations

​Leads & Support Tickets

​AI Agent Execution

​Outbound Campaigns

​Verifying Signatures

​Available Endpoints

Webhooks API

Event Catalog

Telephony & Calls

Messaging & Conversations

Leads & Support Tickets

AI Agent Execution

Outbound Campaigns

Verifying Signatures

Available Endpoints