---
title: "Webhooks"
description: "Hear about deliveries, replies and new customers as they happen."
url: "https://docs.goomzo.africa/docs/developers/webhooks"
docs_index: /llms.txt
lastUpdated: 2026-11-12
section: "Webhooks"
related:
  - /docs/developers/webhooks/events
  - /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.

# Webhooks

> Hear about deliveries, replies and new customers as they happen.

A webhook tells your own system when something happens in Goomzo, so it doesn't have to keep asking. Register a URL,
choose the [events](https://docs.goomzo.africa/docs/developers/webhooks/events?utm_source=llms&utm_medium=ai) it hears, and Goomzo sends each one there as it happens.

## Requirements

- A URL on `https://`, reachable from the internet.
- To manage endpoints through the API, an API key with the `webhooks.manage` permission. In the dashboard, only
  the organization's owner and admins can.

## Add an endpoint

1. Open **Settings → Webhooks** and select **New endpoint**.
2. Enter the URL that will receive events.
3. Choose the events it hears. Choose at least one.
4. Open the endpoint and select **Send test event** to check that your receiver works.

An organization can have up to 10 endpoints. Turn one off to pause it: its events wait and are sent when it's
turned on again.

## Requests

```text
POST /v1/webhook-endpoints
```

### Request syntax

```json
{ "url": "<URL>", "events": ["<EVENT>"] }
```

| Placeholder | Description                                                      | Sample value                          |
| ----------- | ---------------------------------------------------------------- | ------------------------------------- |
| `<URL>`     | _String._ Where events are sent. `https://` only.                | `https://example.com/webhooks/goomzo` |
| `<EVENT>`   | _String._ An [event](https://docs.goomzo.africa/docs/developers/webhooks/events?utm_source=llms&utm_medium=ai) it hears. | `message.delivered`                   |

### Example request

```bash
curl https://api.goomzo.africa/v1/webhook-endpoints \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhooks/goomzo", "events": ["message.delivered", "message.failed"]}'
```

## Responses

The answer includes the endpoint's `secret`, which you use to [check signatures](https://docs.goomzo.africa/docs/developers/webhooks/signatures?utm_source=llms&utm_medium=ai).

## Answer quickly

Answer with any `2xx` status within 15 seconds. Do the slow work afterwards, for example in a queue.

Anything else counts as a failure: another status, a timeout, or no answer. Redirects aren't followed, so use the
final URL. A failed delivery is tried again after 5 seconds, 5 minutes, 30 minutes, then 2, 5, 10 and 10 hours,
with a little randomness so retries don't all arrive at once. After 8 tries, about a day, it's marked failed. If
you answer `429`, `502`, `503` or `504` with a `Retry-After` header, the next try waits at least that long.

<Callout>
  The same event can arrive more than once, and events can arrive out of order. Use `webhook-id` to skip ones you've already handled, and
  the timestamps in `data` to tell which came last.
</Callout>

## When an endpoint is turned off

Goomzo turns an endpoint off, and emails the organization's owner and admins, when:

- it answers `410 Gone`, which asks for no more events, or
- every delivery to it has failed for 5 days.

Its events wait while it's off. Fix the endpoint, then turn it on again in **Settings → Webhooks**.

## The delivery log

Open an endpoint to see its deliveries from the last 30 days: what was sent, how many tries it took, and what
your server answered. Select one to see its full body and your server's response, and select **Resend** to send
it again.

Through the API, list an endpoint's deliveries with `GET /v1/webhook-endpoints/{id}/deliveries`, and send one
again with `POST /v1/webhook-deliveries/{id}/resend`.

## Next steps

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

---

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