> ## 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.
# Partner Webhooks
> One endpoint that receives every event for every merchant connected to you.
# Partner Webhooks
As a partner you configure **one** webhook URL on your partner account. Every merchant that connects to your platform routes its events to that URL — you never configure a webhook per merchant.
Each delivery tells you which merchant it belongs to via `id_store` (and `external_id` / `external_store_id` when the merchant supplied your own identifier).
## Reading your configuration
```bash theme={null}
curl "https://api.wava.co/v1/partners/webhook" \
-H "X-API-Key: YOUR_PARTNER_API_KEY" \
-H "X-API-Secret: YOUR_PARTNER_SECRET_KEY"
```
```json theme={null}
{
"url": "https://your-platform.com/webhooks/wava",
"events": ["store_onboarded", "order_payment", "integration_uninstalled"],
"signing_enabled": true
}
```
The signing key is never returned. If you have lost it, contact [soporte@wava.co](mailto:soporte@wava.co).
## Updating your configuration
```bash theme={null}
curl -X PATCH "https://api.wava.co/v1/partners/webhook" \
-H "X-API-Key: YOUR_PARTNER_API_KEY" \
-H "X-API-Secret: YOUR_PARTNER_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-platform.com/webhooks/wava",
"events": ["store_onboarded", "integration_uninstalled"]
}'
```
Both fields are optional; omitting one leaves it unchanged. The response reports how many integrations were updated — the change is applied across your partner account and all merchant integrations attached to it.
The URL must be `https://`. A plain `http://` URL is rejected with `400 INVALID_WEBHOOK_URL`.
`GET /v1/partners/events` lists the events this endpoint will accept:
```bash theme={null}
curl "https://api.wava.co/v1/partners/events" \
-H "X-API-Key: YOUR_PARTNER_API_KEY" \
-H "X-API-Secret: YOUR_PARTNER_SECRET_KEY"
```
It currently returns the store and integration lifecycle events (`store_onboarded`, `store_updated`, `store_deleted`, `integration_installed`, `integration_uninstalled`). Order and payment-link events are delivered to partners as well, but are configured on your account by Wava rather than through this endpoint — ask [soporte@wava.co](mailto:soporte@wava.co) to add or remove them.
## Testing your endpoint
```bash theme={null}
curl -X POST "https://api.wava.co/v1/partners/webhook/test" \
-H "X-API-Key: YOUR_PARTNER_API_KEY" \
-H "X-API-Secret: YOUR_PARTNER_SECRET_KEY"
```
Wava POSTs a `test.ping` payload to your configured URL, signed the same way real events are, and returns the HTTP status and round-trip time it observed:
```json theme={null}
{
"success": true,
"test_sent": true,
"url": "https://your-platform.com/webhooks/wava",
"response_status": 200,
"response_time_ms": 342,
"error": null
}
```
## Events you receive
| Event | Fires when | Payload |
| ------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `store_onboarded` | A merchant onboarded through your link finishes onboarding, or re-subscribes | Includes the merchant's `merchant_key` — see [Onboarding](/partners/onboarding) |
| `order_payment` | An order for one of your merchants is paid | Same shape as direct API integrations |
| `link_paid` | A payment-link order created via the API is paid (alongside `order_payment`) | See [Webhook Events](/webhooks/events) |
| `integration_uninstalled` | Your integration is removed from a merchant's store | Below |
`order_payment` reaches you for orders created through the API — yours or the merchant's own direct integration. Orders created from the Wava dashboard UI do **not** emit partner webhooks.
### `order_payment`
```json theme={null}
{
"event": "order_payment",
"timestamp": "2026-08-06T15:41:09.220Z",
"id_order": 55217,
"id_external": "your-order-001",
"status": "confirmed",
"total_price": 50000,
"currency": "COP",
"payment_method": {
"gateway": "nequi",
"status": "processed"
},
"totalItems": 1,
"shopper": {
"first_name": "Juan",
"last_name": "Perez",
"email": "juan@email.com"
},
"external_store_id": "your-internal-merchant-id"
}
```
Route it to the right merchant with `external_store_id`, and to the right transaction with `id_external` (the `order_key` you sent) or `id_order`.
### `integration_uninstalled`
```json theme={null}
{
"event": "integration_uninstalled",
"timestamp": "2026-08-06T16:02:44.881Z",
"id_store": 2841,
"external_id": "your-internal-merchant-id",
"store_name": "Café Bogotá"
}
```
Stop billing and stop using that merchant's key when you receive this.
`order_cancelled` and `order_refunded` can be enabled on a partner account, but their payload shape is not finalized and may change without notice. Do not build against them yet.
## Delivery semantics
* Each attempt has a **5 second** timeout. Respond `2xx` immediately and process asynchronously.
* Wava makes up to **3 attempts**, roughly one second apart.
* A `4xx` response is treated as a permanent rejection and is **not** retried. Only connection failures and `5xx` responses are retried.
* A `2xx` response whose JSON body contains `"error": true` is recorded as a **failure**, not a success. Do not return that shape from a handler that succeeded.
* Every attempt is logged with its status, response body and timing, and is visible to Wava support when you report a delivery problem.
Handlers must be idempotent — deduplicate on `id_order` / `id_external` for order events and on `id_store` for store events.
## Verifying deliveries
Partner accounts are created with HMAC signing enabled and a dedicated signing key. Every delivery carries `X-Wava-Signature`; verify it before acting on the payload. See [Webhook Security](/webhooks/security) for the algorithm and code samples.