Cast API

Overview

Base URL. All API endpoints are under:

https://api.cast.wayvzgroup.com

The API speaks JSON: send Content-Type: application/json on POST requests; all responses are JSON. The X-Api-Version: v1 header is included on every response.

Machine-readable spec. The full API is published as an OpenAPI 3.0 document at /v1/openapi. Point your SDK generator, Postman, or an AI coding assistant at it rather than transcribing this page by hand. It needs no API key, and the servers entry reflects whichever host you fetch it from.

Quick test: verify your key

curl "https://api.cast.wayvzgroup.com/v1/ping" \
  -H "Authorization: Bearer sk_live_..."

Endpoint index

Authentication

Cast uses Bearer tokens. Create a key at /developers, then send it on every request:

Authorization: Bearer sk_live_...

Keys start with sk_live_ followed by 32 random characters. They are shown once at creation time. Store them safely. Lost keys can be revoked and replaced from the same page.

Sandbox keys

A key that starts with sk_test_ reads your real data. It never sends, never charges and never erases a contact. Sends, calls, campaigns, journey enrolments, events, contacts, contact properties and verification checks come back with the same response a live key gets, plus "livemode": false and "simulated": true, and nothing is saved. Every response to a key Cast recognises, refusals included (revoked, IP not allowed, rate limit, idempotency), carries an X-Cast-Mode: live or test header.

Events (POST /v1/events, POST /v1/contacts/{phone}/events), contacts (POST /v1/contacts) and properties (POST /v1/contacts/{phone}/properties) are checked like live ones but not stored, so a test key never starts or feeds a journey. A verification check with a test key never checks the code and never uses an attempt.

Two writes are real even with a test key: creating a short link (POST /v1/links), and registering or unregistering a push device (POST and DELETE /v1/push/devices). A device registered with a test key can receive real pushes later from a live send.

Idempotency

If a POST times out you cannot tell whether it went through. Retrying blindly can send the same message twice, and bill you twice. Send an Idempotency-Key header and retrying is safe: Cast replays the original response instead of doing the work again.

curl -X POST "https://api.cast.wayvzgroup.com/v1/messages" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: order-4471-confirmation" \
  -H "Content-Type: application/json" \
  -d '{"to":"9613123456","from":"Cast","text":"Your order is on its way."}'

Use any string you can regenerate for the same logical action. An order ID works well; a random UUID per attempt does not, because a retry must reuse the key.

Keys are scoped to your account and expire after 24 hours. Only successful (2xx) responses are stored, so a failed request can always be retried normally, so a transient outage never gets frozen into a permanent error.

Errors

Cast returns conventional HTTP status codes. Error bodies are always JSON:

{
  "error": {
    "code": "missing_field",
    "message": "Required field(s) missing: to"
  }
}

See the full error codes reference below.

Rate limits

Each API key has one hourly window, and every authenticated response tells you where you stand in it:

Over the limit, Cast answers 429 with the code rate_limit_exceeded and a Retry-After header in seconds. Wait that long and try again. Treat the three headers as optional: an internal key with no limit does not get them. A failed authentication uses none of your window. GET /v1/account returns the same ceiling as rate_limits.requests_per_hour.

Versioning

The major version is in the URL. Today there is one, /v1. A new major version would run beside the old one for at least 12 months.

What can change with no notice

A new endpoint, a new optional request field or parameter, a new response field, a new webhook event, a new field on an event, a new value in a response enum, and a new error code for a new condition. Your code must ignore fields and enum values it does not know.

What needs notice

Removing or renaming an endpoint, a parameter, a response field, an event or an event field. Changing a type. Making an optional field required. Tightening validation so a request that worked now fails. Changing what an existing status code or error code means. Changing how webhooks are signed.

How much notice

At least 180 days between the day a deprecation is announced and the day it is removed. The one exception is a security fix, which can be shorter and is announced the same day with the reason. A surface marked beta gets 30 days.

How you hear about it

An entry on this changelog with the sunset date. deprecated, x-sunset and x-replacement in the OpenAPI spec. Deprecation, Sunset and Link headers on every response from a deprecated endpoint. A deprecated mark in the webhook event catalogue. A note beside the item in the API reference.

OAuth and marketplace

Cast authenticates with API keys. Each key belongs to one account. There are no OAuth apps and no app marketplace today, and no third party can act for several Cast accounts through a single install.

OAuth and a marketplace are on the roadmap, and both wait for a first consumer: a partner that needs to install across many accounts. Until then, API keys stay as they are.

SDKs & tools

Official, dependency-light clients wrap the whole API in idiomatic code. Each mirrors the REST paths (cast.messages.send, cast.whatsapp.send, cast.contacts.upsert, cast.flows.trigger…), detects live vs sandbox from your key, supports the Idempotency-Key, and raises a typed error carrying the stable error code.

JavaScript quickstart

const Cast = require('@cast/sdk');
const cast = new Cast('sk_test_...');            // sandbox: nothing sent or charged

const msg = await cast.messages.send({ to: '96170000000', from: 'CAST', text: 'Hello' });
console.log(msg.id, cast.livemode);              // false on a test key

// safe to retry: the same key replays the first response
await cast.messages.send({ to: '96170000000', text: 'Order #42' },
                         { idempotencyKey: 'order-42' });

try {
  await cast.balance();
} catch (e) {
  if (e.code === 'insufficient_balance') { /* top up */ }
}

Python quickstart

from cast import Cast, CastError
cast = Cast("sk_test_...")

msg = cast.messages.send(to="96170000000", sender="CAST", text="Hello")
cast.whatsapp.send(to="96170000000", template="welcome")
cast.contacts.set_properties("96170000000", plan="vip")

Postman & OpenAPI

Import the ready-made Postman collection (bearer auth pre-wired, an optional Idempotency-Key on every POST), or point any generator at the /v1/openapi spec to build a client in a language that isn't listed above.

SMS

curl -X POST "https://api.cast.wayvzgroup.com/v1/messages" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "9613xxxxxxx",
    "from": "Cast",
    "text": "Your code is 123456"
  }'

const res = await fetch(
  'https://api.cast.wayvzgroup.com/v1/messages',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '9613xxxxxxx',
      from: 'Cast',
      text: 'Your code is 123456'
    })
  }
);
const data = await res.json();
console.log(data.id); // "msg_12345"

import requests

resp = requests.post(
    'https://api.cast.wayvzgroup.com/v1/messages',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json'
    },
    json={
        'to': '9613xxxxxxx',
        'from': 'Cast',
        'text': 'Your code is 123456'
    }
)
print(resp.json()['id'])  # "msg_12345"

$ch = curl_init('https://api.cast.wayvzgroup.com/v1/messages');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer sk_live_...',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to'   => '9613xxxxxxx',
        'from' => 'Cast',
        'text' => 'Your code is 123456'
    ])
]);
$data = json_decode(curl_exec($ch), true);
echo $data['id']; // "msg_12345"

{
  "id": "msg_12345",
  "object": "message",
  "status": "queued",
  "to": ["9613xxxxxxx"],
  "from": "Cast",
  "language": 0,
  "parts": 1,
  "cost": 0.04,
  "currency": "USD",
  "created_at": "2026-05-01T11:00:00Z"
}

curl "https://api.cast.wayvzgroup.com/v1/messages/msg_12345" \
  -H "Authorization: Bearer sk_live_..."

A message that failed carries a failure object: reason (from a closed list), reason_text (a sentence you can show), code (the carrier's own code, when it sent one) and attempts. It is null when there is nothing to report. GET /v1/messages carries it too.

WhatsApp

WhatsApp messages must use a Meta-approved template. Submit and manage templates from the template editor. See Templates for approval tips.

curl -X POST "https://api.cast.wayvzgroup.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "9613xxxxxxx",
    "template_name": "order_shipped",
    "template_language": "en_US",
    "template_category": "UTILITY",
    "template_params": ["Hadi", "AWB-12345"]
  }'

const res = await fetch(
  'https://api.cast.wayvzgroup.com/v1/whatsapp/messages',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '9613xxxxxxx',
      template_name: 'order_shipped',
      template_language: 'en_US',
      template_category: 'UTILITY',
      template_params: ['Hadi', 'AWB-12345']
    })
  }
);
const data = await res.json();
console.log(data.meta_message_id);

import requests

resp = requests.post(
    'https://api.cast.wayvzgroup.com/v1/whatsapp/messages',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json'
    },
    json={
        'to': '9613xxxxxxx',
        'template_name': 'order_shipped',
        'template_language': 'en_US',
        'template_category': 'UTILITY',
        'template_params': ['Hadi', 'AWB-12345']
    }
)
print(resp.json()['meta_message_id'])

$ch = curl_init('https://api.cast.wayvzgroup.com/v1/whatsapp/messages');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer sk_live_...',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to'                => '9613xxxxxxx',
        'template_name'     => 'order_shipped',
        'template_language' => 'en_US',
        'template_category' => 'UTILITY',
        'template_params'   => ['Hadi', 'AWB-12345']
    ])
]);
$data = json_decode(curl_exec($ch), true);
echo $data['meta_message_id'];

{
  "id": "msg_12346",
  "object": "whatsapp_message",
  "status": "queued",
  "to": "9613xxxxxxx",
  "template_name": "order_shipped",
  "template_language": "en_US",
  "template_category": "UTILITY",
  "cost": 0.014,
  "currency": "USD",
  "meta_message_id": "wamid.HBgL...",
  "created_at": "2026-05-01T11:00:00Z"
}

Templates

WhatsApp requires Meta to approve message templates before they can be sent. Submit them from the template editor; approval typically takes 1 to 10 minutes.

Categories

• UTILITY: transactional updates tied to a customer action (order shipped, OTP, appointment reminders). Lowest rate.
• MARKETING: promotions, offers, re-engagement. Higher rate; opt-out compliance required.
• AUTHENTICATION: one-time passwords. Lowest rate, strict format requirements.

Common rejection reasons

• Template body looks promotional but was submitted as UTILITY.
• Variables placed at the very start or end of the body with no surrounding text.
• Missing or vague example values for body variables.
• Header image too large, wrong aspect ratio, or text-heavy image.
• Footer containing URLs, phone numbers, or currency symbols (restricted in some markets).

Contacts: Properties

Contact properties are arbitrary key-value pairs you store per phone number. They power segment conditions (e.g. plan = "premium", lifetimeSpend > 500) and flow branch logic. Values are always stored as strings; Cast auto-casts to numeric/date types for segment comparisons.

curl "https://api.cast.wayvzgroup.com/v1/contacts/9613xxxxxxx/properties" \
  -H "Authorization: Bearer sk_live_..."

{
  "object": "contact_properties",
  "phone": "9613xxxxxxx",
  "properties": {
    "plan": "premium",
    "lifetimeSpend": "1250.00",
    "lastSeen": "2026-04-15"
  }
}

curl -X POST "https://api.cast.wayvzgroup.com/v1/contacts/9613xxxxxxx/properties" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "premium",
    "lifetimeSpend": "1250.00",
    "lastSeen": "2026-04-15"
  }'

await fetch(
  'https://api.cast.wayvzgroup.com/v1/contacts/9613xxxxxxx/properties',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      plan: 'premium',
      lifetimeSpend: '1250.00',
      lastSeen: '2026-04-15'
    })
  }
);

requests.post(
    'https://api.cast.wayvzgroup.com/v1/contacts/9613xxxxxxx/properties',
    headers={'Authorization': 'Bearer sk_live_...'},
    json={'plan': 'premium', 'lifetimeSpend': '1250.00', 'lastSeen': '2026-04-15'}
)

{
  "object": "contact_properties",
  "phone": "9613xxxxxxx",
  "upserted": 3
}

Contacts: Events

Contact events are timestamped actions (e.g. purchase.completed, form.submitted, subscription.renewed). They power event-triggered automation flows and segment conditions. Event type must follow domain.action format: lowercase letters, digits, and underscores only.

curl "https://api.cast.wayvzgroup.com/v1/contacts/9613xxxxxxx/events" \
  -H "Authorization: Bearer sk_live_..."

curl -X POST "https://api.cast.wayvzgroup.com/v1/contacts/9613xxxxxxx/events" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "purchase.completed",
    "payload": {
      "orderId": "ORD-4829",
      "amount": 249.99,
      "currency": "USD"
    }
  }'

await fetch(
  'https://api.cast.wayvzgroup.com/v1/contacts/9613xxxxxxx/events',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'purchase.completed',
      payload: { orderId: 'ORD-4829', amount: 249.99, currency: 'USD' }
    })
  }
);

requests.post(
    'https://api.cast.wayvzgroup.com/v1/contacts/9613xxxxxxx/events',
    headers={'Authorization': 'Bearer sk_live_...'},
    json={
        'type': 'purchase.completed',
        'payload': {'orderId': 'ORD-4829', 'amount': 249.99, 'currency': 'USD'}
    }
)

{
  "object": "contact_event",
  "id": 9001,
  "phone": "9613xxxxxxx",
  "type": "purchase.completed",
  "occurred_at": "2026-05-01T11:00:00Z"
}

Voice

{
  "to": "+9613197119",
  "ttsText": "Hi {firstname}, your driver is two minutes away.",
  "language": "en",
  "voiceId": "en-US-Wavenet-D",
  "speed": 1.0,
  "messageType": "tts",
  "dtmf": {
    "options": { "1": "Confirmed", "2": "Cancel" },
    "timeoutSec": 15
  },
  "callbackUrl": "https://your-app.example.com/cast/voice-callback",
  "metadata": { "orderId": "4821", "driverId": "D-441" }
}

curl -X POST "https://api.cast.wayvzgroup.com/v1/voice/call" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+9613197119",
    "ttsText": "Your pickup is at Hamra Street",
    "language": "en",
    "dtmf": { "options": { "1": "Confirmed", "2": "Cancel" }, "timeoutSec": 15 }
  }'

{
  "id": "vc_abc12345",
  "callSid": "abc12345def67890",
  "status": "queued",
  "to": "+9613197119",
  "estimatedCost": 0.025,
  "createdAt": "2026-05-16T10:30:00Z"
}

{
  "id": "vc_abc12345",
  "callSid": "abc12345def67890",
  "status": "unknown",
  "to": "+9613197119",
  "estimatedCost": 0.025,
  "message": "We could not confirm whether the call was queued. It may still be placed, so it was not tried again, and its charge is kept and recorded until it settles.",
  "createdAt": "2026-05-16T10:30:00Z"
}

{
  "error": {
    "code": "voice_enqueue_failed",
    "message": "Could not enqueue the voice call. The call was not placed, and its charge could not be returned or recorded. Contact support and quote callSid abc12345def67890."
  }
}

Flows

curl "https://api.cast.wayvzgroup.com/v1/flows?status=active" \
  -H "Authorization: Bearer sk_live_..."

{
  "flows": [
    {
      "id": 42,
      "name": "Driver Notification",
      "status": "active",
      "nodeCount": 6,
      "enrollmentsLast24h": 487,
      "createdAt": "2026-05-01T00:00:00Z"
    }
  ],
  "total": 1
}

Contacts

{
  "phone": "+9613197119",
  "firstName": "Ahmad",
  "lastName": "Al-Rashid",
  "email": "ahmad@example.com",
  "properties": {
    "role": "driver",
    "city": "Beirut",
    "vehicle": "motorcycle"
  },
  "groups": ["drivers-beirut"]
}

curl -X POST "https://api.cast.wayvzgroup.com/v1/contacts" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+9613197119", "firstName": "Ahmad", "properties": { "role": "driver" } }'

{
  "phone": "+9613197119",
  "firstName": "Ahmad",
  "lastName": "Al-Rashid",
  "created": false,
  "propertiesSet": 3,
  "groupsAdded": 1
}

Links & Campaigns

{
  "url": "https://cast.wayvzgroup.com/p/toters-promo",
  "slug": "toters-may",
  "utmSource": "api",
  "utmMedium": "sms"
}

curl -X POST "https://api.cast.wayvzgroup.com/v1/links" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/landing", "slug": "promo-may" }'

{
  "shortUrl": "https://slnk.ai/toters-may",
  "slug": "toters-may",
  "destinationUrl": "https://cast.wayvzgroup.com/p/toters-promo",
  "createdAt": "2026-05-16T10:30:00Z"
}

Account

{
  "ok": true,
  "account_id": 1234,
  "now": "2026-05-01T11:00:00Z"
}

rate_limits.requests_per_hour is the ceiling that applies to your key, or null if it has none, and rate_limits.window_seconds is the window. rate_limits.requests_per_second is deprecated: it holds the key's raw setting, 0 when unset, and is removed on or after 2027-05-01.

Audit log

curl "https://api.cast.wayvzgroup.com/v1/audit-log?order=asc&limit=500&starting_after=djE6MTEzNTk3"   -H "Authorization: Bearer sk_live_..."

{
  "object": "list",
  "data": [
    {
      "id": 113598,
      "occurred_at": "2026-10-16T09:14:03.120Z",
      "category": "Security",
      "action": "auth.login",
      "actor": { "username": "amal@example.com", "name": "Amal", "role": "admin", "seat_id": 9651 },
      "entity": { "type": null, "id": null, "label": null },
      "detail": { "seat": 9651 },
      "ip": "203.0.113.9",
      "user_agent": "Mozilla/5.0 ..."
    }
  ],
  "count": 1,
  "limit": 500,
  "order": "asc",
  "has_more": false,
  "next_cursor": "djE6MTEzNTk4"
}

Webhooks

Cast can POST a JSON event to your URL whenever something happens to a message. Configure endpoints at /developers/webhooks.

Every request has the same envelope: id, type, created (unix seconds), apiVersion and data. Ignore fields and values you do not recognise: Cast can add them at any time. The same list is at /v1/webhook-events as JSON. Deprecated fields are marked below.

Event types

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "message.delivered",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "messageId": "wamid.HBgLOTYxNzAxMjM0NTY3",
    "smsLogId": "12345",
    "to": "96170123456",
    "channel": "whatsapp",
    "templateName": "order_shipped",
    "templateLanguage": "en_US",
    "sentAt": "2026-05-01T10:59:58Z",
    "deliveredAt": "2026-05-01T11:00:05Z",
    "readAt": null,
    "failedAt": null,
    "failureCode": null,
    "failureReason": null
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "message.read",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "messageId": "wamid.HBgLOTYxNzAxMjM0NTY3",
    "smsLogId": "12345",
    "to": "96170123456",
    "channel": "whatsapp",
    "templateName": "order_shipped",
    "templateLanguage": "en_US",
    "sentAt": "2026-05-01T10:59:58Z",
    "deliveredAt": "2026-05-01T11:00:05Z",
    "readAt": null,
    "failedAt": null,
    "failureCode": null,
    "failureReason": null
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "message.failed",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "messageId": "wamid.HBgLOTYxNzAxMjM0NTY3",
    "smsLogId": "12345",
    "to": "96170123456",
    "channel": "whatsapp",
    "templateName": "order_shipped",
    "templateLanguage": "en_US",
    "sentAt": "2026-05-01T10:59:58Z",
    "deliveredAt": "2026-05-01T11:00:05Z",
    "readAt": null,
    "failedAt": null,
    "failureCode": null,
    "failureReason": null
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "message.inbound",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "messageId": "wamid.HBgLOTYxNzAxMjM0NTY3",
    "channel": "whatsapp",
    "from": "96170123456",
    "to": "102938475610293",
    "type": "text",
    "body": "Hello, I need help with my order",
    "isOptOut": false,
    "isHelpRequest": false,
    "receivedAt": "2026-05-01T11:00:05Z"
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "conversation.status_changed",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "customerPhone": "96170123456",
    "channel": "whatsapp",
    "status": 2,
    "statusName": "resolved",
    "isPinned": false,
    "changedByAgentID": 17,
    "reason": "agent",
    "changedAt": "2026-05-01T11:00:05Z"
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "conversation.assigned",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "customerPhone": "96170123456",
    "channel": "whatsapp",
    "action": "assigned",
    "agentID": 17,
    "agentName": "Lina",
    "byUserID": "c0a80164-0000-4000-8000-000000000001",
    "source": "agent",
    "changedAt": "2026-05-01T11:00:05Z"
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "note.added",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "noteID": 981,
    "customerPhone": "96170123456",
    "channel": "whatsapp",
    "agentID": 17,
    "body": "Called about an invoice.",
    "createdAt": "2026-05-01T11:00:05Z"
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "bulk.completed",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "jobId": "7a1f4c1e-2b1d-4c1a-9e0b-3c1d2e4f5a6b",
    "action": "set_status",
    "status": "completed",
    "total": 1500,
    "done": 1500,
    "updated": 1480,
    "skipped": 20,
    "failed": 0,
    "failReason": null,
    "perConversationEvents": 1000,
    "perConversationLimit": 1000,
    "finishedAt": "2026-05-01T11:00:05Z"
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "email.opened",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "channel": "email",
    "to": "lina@example.com",
    "smsLogId": "12345",
    "campaignId": "3f2b8c1e-6a0d-4b57-9a11-5f0c2e7d1a44",
    "occurredAt": "2026-05-01T11:00:05Z"
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "email.clicked",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "channel": "email",
    "to": "lina@example.com",
    "smsLogId": "12345",
    "campaignId": "3f2b8c1e-6a0d-4b57-9a11-5f0c2e7d1a44",
    "occurredAt": "2026-05-01T11:00:05Z",
    "url": "https://example.com/offer"
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "email.bounced",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "channel": "email",
    "to": "lina@example.com",
    "smsLogId": "12345",
    "campaignId": "3f2b8c1e-6a0d-4b57-9a11-5f0c2e7d1a44",
    "occurredAt": "2026-05-01T11:00:05Z",
    "reason": "SES Permanent",
    "bounceType": "hard"
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "email.complained",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "channel": "email",
    "to": "lina@example.com",
    "smsLogId": "12345",
    "campaignId": "3f2b8c1e-6a0d-4b57-9a11-5f0c2e7d1a44",
    "occurredAt": "2026-05-01T11:00:05Z",
    "reason": "SES Complaint"
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "email.unsubscribed",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "channel": "email",
    "to": "lina@example.com",
    "smsLogId": "12345",
    "campaignId": "3f2b8c1e-6a0d-4b57-9a11-5f0c2e7d1a44",
    "occurredAt": "2026-05-01T11:00:05Z",
    "reason": "one-click"
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "conversion.recorded",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "conversionId": 8123,
    "offerId": 42,
    "clickId": "9d6b1f3a-2c44-4e0a-8f51-1b2c3d4e5f60",
    "eventType": "sale",
    "status": "approved",
    "payout": 12.5,
    "currency": "USD",
    "convertedAt": "2026-05-01T11:00:05Z",
    "source": "postback",
    "campaignId": "3f2b8c1e-6a0d-4b57-9a11-5f0c2e7d1a44"
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "conversion.reversed",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "conversionId": 8123,
    "offerId": 42,
    "clickId": "9d6b1f3a-2c44-4e0a-8f51-1b2c3d4e5f60",
    "eventType": "sale",
    "status": "reversed",
    "payout": 12.5,
    "currency": "USD",
    "convertedAt": "2026-05-01T11:00:05Z",
    "source": "postback",
    "campaignId": "3f2b8c1e-6a0d-4b57-9a11-5f0c2e7d1a44"
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "segment.alert",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "segmentId": 42,
    "segmentName": "VIP customers",
    "rule": "size_below",
    "threshold": 1000,
    "size": 900,
    "state": "firing",
    "windowHours": 24
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "audit.batch",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "prev_last_id": 113597,
    "first_id": 113602,
    "last_id": 113602,
    "count": 1,
    "events": []
  }
}

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "type": "test",
  "created": 1777633205,
  "apiVersion": "v1",
  "data": {
    "message": "This is a Cast webhook test event. Your integration is working.",
    "test": true
  }
}

Signature verification

Every request includes a Cast-Signature header:

Cast-Signature: t=1746090000,v1=<hex>

Where v1 is hex(HMAC_SHA256(secret, t + "." + body)). To verify:

1. Read the raw request body (do not parse first).
2. Parse t and v1 from the header.
3. Reject if t is more than 5 minutes old (replay protection).
4. Compute hex(HMAC_SHA256(secret, t + "." + body)) and compare to v1 using constant-time comparison.

const crypto = require('crypto');

function verifyCastSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(',').map(kv => kv.split('=')));
  const t = parts.t;
  const v1 = parts.v1;
  if (!t || !v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(t + '.' + rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(v1, 'hex'));
}

import hmac, hashlib, time

def verify_cast_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(','))
    t, v1 = parts.get('t'), parts.get('v1')
    if not t or not v1: return False
    if abs(time.time() - int(t)) > 300: return False

    expected = hmac.new(
        secret.encode(),
        f"{t}.{raw_body.decode()}".encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, v1)

function verifyCastSignature(string $rawBody, string $header, string $secret): bool {
    parse_str(str_replace(',', '&', $header), $parts);
    if (empty($parts['t']) || empty($parts['v1'])) return false;
    if (abs(time() - intval($parts['t'])) > 300) return false;

    $expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1']);
}

Retry policy

If your endpoint returns anything other than 2xx, Cast retries with exponential backoff:

• +30 seconds after attempt 1
• +5 minutes after attempt 2
• +30 minutes after attempt 3
• +2 hours after attempt 4
• +6 hours after attempt 5
• +12 hours after attempt 6
• After 7 attempts (20 hours 35 minutes in all) the event is marked dead and leaves the retry queue.

Each request includes Cast-Event-Id, Cast-Event-Type, and Cast-Delivery-Attempt headers for deduplication and tracing.

Audit log stream (audit.batch)

Tick Send audit events to this endpoint on an endpoint at /developers/webhooks and Cast sends it the new entries of your audit log as they are written, in batches. It suits any system that accepts a signed HTTPS POST. Up to 3 endpoints per account can take the stream. The option, and changing the address of an endpoint that takes it, pausing, resuming or deleting it, and rotating its secret, are for people allowed to export the audit log (account owners and admins by default). Each of these is recorded in the audit log (audit.siem_enable, audit.siem_disable, audit.siem_destination_change). Turning the stream off, or deleting the endpoint, cancels the batches still waiting for it: nothing more is sent to it.

The stream starts from the moment it is turned on: earlier entries are not sent, and turning it off and on again, pausing and resuming the endpoint, or deleting the endpoint and adding a new one, starts again from that moment. Batches that were waiting from before a pause are not sent on resume. To fetch history, use GET /v1/audit-log. A batch usually arrives within a couple of minutes of the entry being written.

{
  "id": "evt_9b41d7...",
  "type": "audit.batch",
  "created": 1746354660,
  "data": {
    "prev_last_id": 113597,
    "first_id": 113602,
    "last_id": 113655,
    "count": 2,
    "events": [
      { "id": 113602, "occurred_at": "2026-05-04T10:30:12.417Z", "category": "Security", "action": "auth.login", ... },
      { "id": 113655, "occurred_at": "2026-05-04T10:30:40.090Z", "category": "Team", "action": "team.role_change", ... }
    ]
  }
}

Signing and retries are the same as every other event: a Cast-Signature header over the raw body, Cast-Event-Type: audit.batch, and the retry schedule above (about 20 hours).

When an endpoint falls behind. While an endpoint that is keeping up has three batches waiting to be delivered, Cast pauses the stream and queues nothing new, so nothing is lost while it catches up. An endpoint that is failing (its oldest waiting batch has already failed once) does not pause the others. If every endpoint is failing, the stream pauses too. Once a batch gets through again, that endpoint's other waiting batches are retried straight away. What can still be lost: a batch the retry schedule gives up on (about 20 hours of failures), and, while another endpoint keeps the stream moving, new batches for a failing endpoint that already has 10 waiting. Both show up as a gap in the chain below.

Ordering and gaps. Delivery is at least once, and after a retry batches can arrive out of order. De-duplicate entries by id and sort them by id or occurred_at. Ids are unique but not consecutive (one sequence is shared by every Cast account), so use the chain to detect a gap: each batch's prev_last_id equals the last_id of the batch before it. If you see a prev_last_id you have no batch for, fetch the missing range with GET /v1/audit-log?order=asc&starting_after=.... Entries are held back for five seconds after they are written so that ones still being saved are not passed over; an entry that takes longer than that to be saved can be missed by the stream, so reconcile against the API by time range from time to time if you need every entry.

Send test on an endpoint that takes the stream sends a sample audit.batch with one entry whose action is audit.test, "test": true on the batch and the entry, and null chain ids. It is not part of the chain and is not written to your audit log.

Entries carry the same personal data as the audit log itself: the acting user's email and name, their IP address and browser, and free text that can include a customer's name or phone number. Point the stream only at a system you are allowed to store that data in.

HTTP status codes

Error codes

Conversion postback

A signed POST /api/postback.ashx from an advertiser records a conversion against a click. When the conversion carries money, the JSON answer says what was written:

The three fields are left out when no money was recorded. In the request, a missing or null payout can take the offer's fixed amount if the offer names that event as payable. An explicit 0 means no payout. A value that is not a number records no payout and never falls back to the offer.

Changelog

The full list and the versioning policy are at /developers/changelog.