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

# Webhooks

> Receive real-time notifications when order status changes.

# Webhooks

Webhooks notify your server when events occur in the Wava platform — most importantly, when a payment is confirmed. Instead of polling for status, your server receives an HTTP POST request with the event data.

## Setup

Configure your webhook URL in the [Wava Dashboard](https://app.wava.co) under **Settings > Integrations > API**. You can set different URLs for development and production environments.

Your endpoint must:

* Accept `POST` requests
* Respond with a `200` status code within 5 seconds
* Be accessible over HTTPS (production)

## How webhooks work

### Direct API integrations

When a merchant integrates directly with the Wava API, webhooks are sent to the webhook URL configured in their dashboard. The primary event is `order_payment` (sent when a payment is confirmed).

### Partner integrations

Partners receive a different set of webhooks depending on the event type:

* **Order webhooks**: Sent to the partner's webhook URL when an order created through the partner is paid (same payload as direct API webhooks).
* **Store onboarding webhooks**: Sent to the partner when a new store is onboarded on their platform.

## Webhook payload

Payloads are a **flat JSON object** — every field is at the top level (there is no nested `data` wrapper). Every payload includes the `event` name and a top-level `timestamp` (ISO 8601). When a payment is confirmed, Wava sends:

```json theme={null}
{
  "event": "order_payment",
  "timestamp": "2026-06-24T02:05:12.952Z",
  "id_order": 12345,
  "id_external": "order-12345",
  "status": "confirmed",
  "total_price": 50000,
  "currency": "COP",
  "payment_method": {
    "gateway": "nequi",
    "status": "processed"
  },
  "totalItems": 1,
  "shopper": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com"
  },
  "external_store_id": null
}
```

Field notes:

* `total_price` is the order total (not `amount`). `currency` is the ISO 4217 code (e.g. `COP`).
* `payment_method` is an **object**; the gateway is `payment_method.gateway` (e.g. `nequi`, `breb`, `daviplata`).
* `id_external` is the `order_key` you provided when creating the order (`null` if none). Use it — or `id_order` — to match webhooks to your records and to deduplicate retries.
* `external_store_id` is your external store reference (`null` if none).

<Note>
  Payment links **created via the API** (`source: "api"`) also emit a `link_paid` event in addition to `order_payment` for the same order. Payment links created from the Wava **dashboard UI** (`source: "wava"`) do **not** trigger webhooks. See [Webhook Events](/webhooks/events) for the `link_paid` payload.
</Note>

## Retry policy

If your endpoint does not respond with a `200` status code, Wava retries the webhook with exponential backoff. After multiple failed attempts, the webhook is marked as failed and can be reviewed in the dashboard.

<Tip>
  Always respond with `200` immediately, then process the webhook data asynchronously. This prevents timeouts and ensures reliable delivery.
</Tip>