> ## Documentation Index
> Fetch the complete documentation index at: https://timelines.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# WABA API Webhooks Overview

> Receive real-time notifications for WhatsApp Business Platform (WABA) events in your workspace

# WABA API Webhooks

WABA API Webhooks deliver real-time notifications when WhatsApp Business Platform events occur in your TimelinesAI workspace. They use the same subscription mechanism, delivery model, and retry policy as the regular [PublicAPI Webhooks](https://timelines.ai/docs/webhook-reference/overview.md) — the difference is the set of WABA-specific event types and payload shapes described below.

## How it works

**1. Register a webhook**

Use `POST /webhooks` to subscribe to a WABA event type and provide your endpoint URL

**2. An event occurs**

A WABA message arrives, a WABA chat changes state, a template is reviewed by Meta, or an account status changes

**3. You receive a POST request**

TimelinesAI sends the event payload to your endpoint in real-time

**4. Acknowledge receipt**

Your server responds with a 2xx status within 5 seconds

## Available events

### WABA message events

| Event | Trigger | Description |
| - | - | - |
| `waba:message:received` | Incoming WABA message | A contact sends a message on a WABA account |
| `waba:message:delivered` | Outbound message delivered | An outbound WABA message is delivered to the contact |
| `waba:message:failed` | Outbound message failed | An outbound WABA message fails to send (includes structured `failure_reason`) |
| `waba:message:read` | Outbound message read | An outbound WABA message is read by the contact |

### WABA chat events

| Event | Trigger | Description |
| - | - | - |
| `waba:chat:incoming` | New incoming WABA chat | A contact initiates a WABA conversation |
| `waba:chat:outgoing` | New outgoing WABA chat | You start a new WABA conversation |
| `waba:chat:assigned` | WABA chat (re)assigned | A WABA chat is assigned to a workspace member (payload carries the responsible member) |
| `waba:chat:unassigned` | WABA chat unassigned | A WABA chat's assignment is removed |
| `waba:chat:closed` | WABA chat closed | A WABA chat is closed |
| `waba:chat:reopened` | WABA chat reopened | A WABA chat is reopened |

### WABA account events

| Event | Trigger | Description |
| - | - | - |
| `waba:account:active` | Account active | A WABA account becomes active |
| `waba:account:disabled` | Account disabled | A WABA account is disabled |
| `waba:account:disconnected` | Account disconnected | A WABA account is disconnected (removed) |

### WABA template events

| Event | Trigger | Description |
| - | - | - |
| `waba:template:approved` | Template approved | A WABA message template is approved by Meta |
| `waba:template:rejected` | Template rejected | A WABA message template is rejected by Meta |
| `waba:template:disabled` | Template disabled | A WABA message template is disabled or pending deletion |

> [!NOTE]
>
> **Failed messages** — `waba:message:failed` carries a structured `failure_reason` object with `code`, `title`, and `details`. It is present only on the failed event and omitted for `received`, `delivered`, and `read`.

> [!NOTE]
>
> **Payload shapes** — WABA message webhook events bundle the account, chat, and message objects together in a single payload. Each event group has its own schema — see the individual event pages for the exact fields.

## Endpoint requirements

Your webhook endpoint must:

> [!TIP]
>
> Be publicly accessible (no localhost in production)

> [!TIP]
>
> Use HTTPS

> [!TIP]
>
> Respond with a 2xx status within 5 seconds

> [!TIP]
>
> Accept POST requests with JSON body

## Managing webhooks

WABA webhook subscriptions are managed via the same Public API endpoints as regular webhooks:

| Action | Endpoint |
| - | - |
| List all | `GET /webhooks` |
| Create | `POST /webhooks` |
| Get details | `GET /webhooks/{id}` |
| Update | `PUT /webhooks/{id}` |
| Delete | `DELETE /webhooks/{id}` |

See the [Webhooks guide](https://timelines.ai/docs/guides/webhooks.md) for setup instructions and code examples.

## Next steps

> [card] [WABA API](https://timelines.ai/docs/public-api-reference/waba/overview.md)
>
> Explore all WABA API endpoints

> [card] [PublicAPI Webhooks](https://timelines.ai/docs/webhook-reference/overview.md)
>
> Regular WhatsApp webhook events


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.