---
title: "Events"
description: "Every event Goomzo sends, and what each one carries."
url: "https://docs.goomzo.africa/docs/developers/webhooks/events"
docs_index: /llms.txt
lastUpdated: 2026-11-12
section: "Webhooks"
related:
  - /docs/developers/webhooks
  - /docs/developers/webhooks/signatures
---

> For an index of all documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt). Any page is also available as Markdown by adding .md to its URL.

# Events

> Every event Goomzo sends, and what each one carries.

An event is one thing that happened, sent to every endpoint that hears it as a `POST` with a JSON body.

## Events

| Event                | When                                                              |
| -------------------- | ----------------------------------------------------------------- |
| `message.sent`       | The gateway took a message.                                       |
| `message.delivered`  | A message reached the customer's phone.                           |
| `message.read`       | The customer read a message. WhatsApp only.                       |
| `message.failed`     | A message couldn't be sent or delivered. `error` says why.        |
| `message.received`   | A customer sent you a message on WhatsApp.                        |
| `broadcast.finished` | A broadcast finished going out, or couldn't. Includes its counts. |
| `customer.created`   | A customer was added, one by one, through the API or by import.   |
| `sms.balance_low`    | Fewer than 100 SMS are left. Sent once each time it falls below.  |
| `webhook.test`       | Only when you select **Send test event**.                         |

## Payloads

Each event is a `POST` with a JSON body:

```json
{
  "id": "evt_4hq2v9n1c8x0t6pk",
  "type": "message.delivered",
  "timestamp": "2026-11-08T09:30:00Z",
  "organizationId": "org_...",
  "data": {
    "id": "msg_...",
    "broadcastId": null,
    "customerId": "cus_...",
    "channel": "sms",
    "to": { "name": "Amina Mushi", "phone": "+255712345678" },
    "status": "delivered",
    "error": null,
    "cost": 1,
    "sentAt": "2026-11-08T09:29:58Z",
    "deliveredAt": "2026-11-08T09:30:00Z",
    "failedAt": null,
    "test": false
  }
}
```

`data` depends on the event:

- **Messages:** `id`, `broadcastId`, `customerId`, `channel`, `to` (`name`, and `phone` or `email`), `status`,
  `error`, `cost`, `sentAt`, `deliveredAt`, `readAt`, `failedAt` and `test`. A read receipt that arrives before
  the delivery report sends only `message.read`.
- **`message.received`:** `id`, `customerId`, `channel`, `from` (their number), `name` (their WhatsApp name),
  `kind` (`text`; `button` or `list` for an option they chose; `reaction`; `image`, `video`, `audio`, `document`
  or `sticker`; `location`; `contacts`; or `unsupported`), `text` (a file's caption), `attachment`, `replyTo`
  (the id of the message it answers, or null) and `receivedAt`. `attachment` describes a file, place or contact
  cards; a file's `url` serves it with your API key once its `state` is `kept`, usually a few seconds after
  the event.
- **`broadcast.finished`:** `id`, `name`, `channel`, `status` (`sent` or `failed`), `error`, `recipients`,
  `sent`, `delivered`, `failed` and `test`.
- **`customer.created`:** `id`, `name`, `phone`, `email` and `attributes`.
- **`sms.balance_low`:** `left` and `threshold`.

## Next steps

- [Signatures](https://docs.goomzo.africa/docs/developers/webhooks/signatures?utm_source=llms&utm_medium=ai)
- [Webhooks](https://docs.goomzo.africa/docs/developers/webhooks?utm_source=llms&utm_medium=ai)

---

For an index of all available documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt)