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
The signing key is never returned. If you have lost it, contact soporte@wava.co.
Updating your configuration
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:
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 to add or remove them.
Testing your endpoint
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:
Events you receive
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
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
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 for the algorithm and code samples.
