> For the complete documentation index, see [llms.txt](https://docs.taqnyat.sa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.taqnyat.sa/api-reference/api-integration-guide/webhooks/webhook-overview.md).

# Webhook Overview

Webhooks allow your application to receive real-time updates from the Taqnyat WhatsApp API.

Taqnyat sends webhook notifications as HTTP `POST` requests to a callback URL configured by the client. These notifications can include:

* Message delivery status updates.
* Incoming WhatsApp messages.
* Contact information related to inbound messages.

### Callback Method

Webhook notifications are sent using:

```http
POST <YOUR_CALLBACK_URL>
```

Your server should be publicly accessible and able to receive HTTP `POST` requests.

### Expected Response

When your application receives a webhook, it should return an HTTP response in the `2xx` success range.

Example:

```http
HTTP/1.1 200 OK
```

If Taqnyat does not receive a successful response, the callback may be retried up to **three times**.

### Callback Structure

A callback can contain the following top-level fields:

| Field           | Type   | Description                                                   |
| --------------- | ------ | ------------------------------------------------------------- |
| `type`          | String | Identifies the callback type. The value is always `whatsapp`. |
| `statuses`      | Array  | Contains message delivery reports.                            |
| `contacts`      | Array  | Contains contact information related to inbound messages.     |
| `notifications` | Array  | Contains incoming WhatsApp messages.                          |

### Example Callback Structure

```json
{
  "type": "whatsapp",
  "statuses": [],
  "contacts": [],
  "notifications": []
}
```

The actual content of each array depends on the event being received.

A single callback may contain both **delivery reports** and **incoming messages**.

### Webhook Processing

When receiving a callback, your application should:

1. Accept the incoming `POST` request.
2. Read the relevant callback object.
3. Process the event according to its type.
4. Return a `2xx` response as soon as the callback is successfully received.
5. Handle repeated callbacks safely in case a webhook is retried.

### Webhook Types

The next sections explain the two primary callback types:

**Delivery Status Callback**\
Used to track message states such as queued, sent, delivered, read, or failed.

**Incoming Message Callback**\
Used to receive messages sent by WhatsApp users to your business number.

> Your application should not assume that only one callback type will appear in each request, since delivery reports and inbound messages can be included together.