Create webhook

POST

api

webhooks

curl -X POST "https://api.sayvy.ai/api/v1/webhooks" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/api/webhooks/sayvy",
    "events": [
      "call.completed",
      "message.received",
      "campaign.completed"
    ]
  }'

import requests

url = "https://api.sayvy.ai/api/v1/webhooks"

payload = {
    "url": "https://example.com/api/webhooks/sayvy",
    "events": [
        "call.completed",
        "message.received",
        "campaign.completed"
    ]
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code)
print(response.json())

const response = await fetch("https://api.sayvy.ai/api/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    url: "https://example.com/api/webhooks/sayvy",
    events: ["call.completed", "message.received"]
  })
});

const data = await response.json();
console.log(data);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sayvy.ai/api/v1/webhooks"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
      {
        "url": "https://example.com/api/webhooks/sayvy",
        "events": ["call.completed", "message.received"]
      }
    """))
    .build();

HttpResponse<String> response =
    HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

{
  "id": "8f3b0e2a-71d3-4a5f-9e6b-123456789abc",
  "organization_id": "93f35dc2-5d46-4e58-a9ee-038c35d9bcf1",
  "url": "https://example.com/api/webhooks/sayvy",
  "secret": "whsec_3b9f8a12e4c7d018b249aef567890123",
  "events": [
    "call.completed",
    "message.received",
    "campaign.completed"
  ],
  "is_active": true,
  "created_at": "2026-09-07T12:30:00Z",
  "updated_at": "2026-09-07T12:30:00Z"
}

{
  "detail": "Invalid events specified: foo.bar. Allowed events: call.started, call.completed..."
}

{
  "detail": "Unauthorized"
}

Register a new webhook subscription to receive real-time HTTP POST notifications. Each subscription generates a cryptographically secure secret used to verify webhook signatures.

Authentication

This endpoint requires Bearer token authentication.

Authorization: Bearer <token>

Header	Type	Required	Description	Format
`Authorization`	`string`	Yes	Scoped organization API key or Bearer JWT token	`Bearer <token>`

Input parameters

The following parameters are accepted in the JSON request body.

string

required

Bearer token for authentication. Format: Bearer <token>.

string

required

Your server’s HTTPS callback URL. Must begin with http:// or https://. Example: https://example.com/api/webhooks/sayvy.

string[]

required

Array of event topics to subscribe to. Must contain at least one valid event name (e.g. ["call.completed", "message.received", "campaign.completed"]).

Show Allowed event names

message.received, message.sent, message.failed
conversation.started, conversation.closed
lead.created, lead.updated
ticket.created, ticket.assigned, ticket.resolved
ai.reply.generated, ai.tool.executed, agent.handoff
call.started, call.completed
campaign.started, campaign.completed, campaign.message.delivered, campaign.message.failed

Response Fields

string

Generated UUID identifier of the webhook subscription.

string

UUID of the organization owning the subscription.

string

Configured callback URL.

string

HMAC SHA-256 signing secret key used to verify the X-Sayvy-Signature header.

string[]

Array of subscribed event types.

boolean

Operational state of the subscription (initially true).

string

ISO 8601 creation timestamp.

string

ISO 8601 modification timestamp.

curl -X POST "https://api.sayvy.ai/api/v1/webhooks" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/api/webhooks/sayvy",
    "events": [
      "call.completed",
      "message.received",
      "campaign.completed"
    ]
  }'

import requests

url = "https://api.sayvy.ai/api/v1/webhooks"

payload = {
    "url": "https://example.com/api/webhooks/sayvy",
    "events": [
        "call.completed",
        "message.received",
        "campaign.completed"
    ]
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code)
print(response.json())

const response = await fetch("https://api.sayvy.ai/api/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    url: "https://example.com/api/webhooks/sayvy",
    events: ["call.completed", "message.received"]
  })
});

const data = await response.json();
console.log(data);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sayvy.ai/api/v1/webhooks"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
      {
        "url": "https://example.com/api/webhooks/sayvy",
        "events": ["call.completed", "message.received"]
      }
    """))
    .build();

HttpResponse<String> response =
    HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

{
  "id": "8f3b0e2a-71d3-4a5f-9e6b-123456789abc",
  "organization_id": "93f35dc2-5d46-4e58-a9ee-038c35d9bcf1",
  "url": "https://example.com/api/webhooks/sayvy",
  "secret": "whsec_3b9f8a12e4c7d018b249aef567890123",
  "events": [
    "call.completed",
    "message.received",
    "campaign.completed"
  ],
  "is_active": true,
  "created_at": "2026-09-07T12:30:00Z",
  "updated_at": "2026-09-07T12:30:00Z"
}

{
  "detail": "Invalid events specified: foo.bar. Allowed events: call.started, call.completed..."
}

{
  "detail": "Unauthorized"
}

‹ Previous

List webhooks

GET /api/v1/webhooks

Next ›

curl -X POST "https://api.sayvy.ai/api/v1/webhooks" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/api/webhooks/sayvy",
    "events": [
      "call.completed",
      "message.received",
      "campaign.completed"
    ]
  }'

import requests

url = "https://api.sayvy.ai/api/v1/webhooks"

payload = {
    "url": "https://example.com/api/webhooks/sayvy",
    "events": [
        "call.completed",
        "message.received",
        "campaign.completed"
    ]
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code)
print(response.json())

const response = await fetch("https://api.sayvy.ai/api/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    url: "https://example.com/api/webhooks/sayvy",
    events: ["call.completed", "message.received"]
  })
});

const data = await response.json();
console.log(data);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sayvy.ai/api/v1/webhooks"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
      {
        "url": "https://example.com/api/webhooks/sayvy",
        "events": ["call.completed", "message.received"]
      }
    """))
    .build();

HttpResponse<String> response =
    HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

{
  "id": "8f3b0e2a-71d3-4a5f-9e6b-123456789abc",
  "organization_id": "93f35dc2-5d46-4e58-a9ee-038c35d9bcf1",
  "url": "https://example.com/api/webhooks/sayvy",
  "secret": "whsec_3b9f8a12e4c7d018b249aef567890123",
  "events": [
    "call.completed",
    "message.received",
    "campaign.completed"
  ],
  "is_active": true,
  "created_at": "2026-09-07T12:30:00Z",
  "updated_at": "2026-09-07T12:30:00Z"
}

{
  "detail": "Invalid events specified: foo.bar. Allowed events: call.started, call.completed..."
}

{
  "detail": "Unauthorized"
}

Overview

Agents

Campaigns

Contacts

CRM

Templates

Knowledge Base

Webhooks

Call Logs

Quick Replies

Inbox

Authentication

Input parameters

Response Fields

​Authentication

​Input parameters

​Response Fields

Authentication

Input parameters

Response Fields