broadcast.status

API reference/Webhook events

Copy page

broadcast.status

Sent each time a broadcast changes status. Use it to follow a broadcast to the end without polling. data is the Broadcast.

Called Broadcast status changed in the app. Part of the plan feature webhooks.broadcasts. To subscribe over the API, the key needs broadcasts:read.

Delivered

{
  "id": "evt_3a5caf5be904576a59951cdd830bad3c",
  "type": "broadcast.status",
  "api_version": "2026-10-14",
  "created_at": "2026-10-14T09:33:08.988Z",
  "workspace_id": "2b7e4c1a-9d3f-4a85-b6e2-5f0c8d1a7e34",
  "data": {
    "id": "2e4a6c8e-0b1d-4f3a-a5c7-9e1b3d5f7a2c",
    "name": "Diwali offer",
    "status": "completed",
    "template": {
      "id": "8d2f4c1e-7a3b-4e59-b0c6-1f2e3d4c5b6a",
      "name": "diwali_offer",
      "language": "en"
    },
    "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
    "send_at": null,
    "started_at": "2026-10-14T09:31:40.912Z",
    "completed_at": "2026-10-14T09:33:08.774Z",
    "paused_reason": null,
    "counts": {
      "total": 250,
      "sent": 247,
      "delivered": 244,
      "read": 171,
      "failed": 3,
      "replied": 21,
      "clicked": 14
    },
    "skipped": {
      "opted_out": 6,
      "duplicate": 2,
      "invalid_phone": 1
    },
    "created_by": {
      "type": "api_key",
      "id": "5e1d2c3b-4a59-4f68-8e7d-6c5b4a392817",
      "name": "Order system"
    },
    "created_at": "2026-10-14T09:31:40.552Z"
  }
}

Show all 42 linesShow less

Headers

webhook-id

The delivery’s ID, the same on every try.

webhook-timestamp

When this try was sent, in Unix seconds.

webhook-signature

v1, and an HMAC-SHA256 of the request.

How delivery and retries work

Data

What’s in data. Every event wraps it in the same envelope.

id string · uuid

name string

status string

preparing: its audience is being collected. scheduled: waiting for send_at. queued: about to send. processing: sending. paused: stopped, by a person or for paused_reason. missed: it couldn’t start at its time. More values may be added.

One of preparing scheduled queued processing paused completed cancelled failed missed.

template object · nullable

The template it sends; null if the template was deleted.

Show 3 child attributesHide child attributes

template.id string · uuid

template.name string

template.language string

number_id string · uuid · nullable

The number it sends from; null if the number was removed.

send_at string · date-time · nullable

When a scheduled broadcast sends; null for one sent at once.

started_at string · date-time · nullable

completed_at string · date-time · nullable

paused_reason string · nullable

Why it stopped, in plain words for people, such as the monthly limit.

counts object

What happened to its messages so far. replied and clicked count recipients who replied, or tapped a quick-reply button, after its message.

Show 7 child attributesHide child attributes

counts.total integer

counts.sent integer

counts.delivered integer

counts.read integer

counts.failed integer

counts.replied integer

counts.clicked integer

skipped object

The customers left out, and why.

Show 3 child attributesHide child attributes

skipped.opted_out integer

Contacts who opted out of marketing messages (MARKETING templates only).

skipped.duplicate integer

A number already listed.

skipped.invalid_phone integer

created_by object

Who created the broadcast: a team member, an API key or another actor.

Show 3 child attributesHide child attributes

created_by.type string

Who or what it was: a team member, an API key, the chatbot, the AI, an automation, a broadcast, the WhatsApp Business app or Soosh itself. More values may be added.

One of user api_key bot ai automation broadcast whatsapp_app system.

created_by.id string · uuid · nullable

The person, key or broadcast. null for actors without one, such as the chatbot.

created_by.name string

created_at string · date-time

Handling it

• Answer with any 2xx within 10 seconds. Do the work after.
• Check the signature first. Verify webhooks has the code.
• Subscribe with POST /v1/webhooks, events: ["broadcast.status"].