Skip to main content

​
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 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 configure one webhook URL on their partner account — not one per merchant — and receive events for every merchant connected to them:
  • store_onboarded: sent when a merchant connects the partner’s platform. Carries that merchant’s merchant_key, which the partner then uses to create orders and links for them.
  • Order webhooks (order_payment, link_paid): sent when an API-created order for one of the partner’s merchants is paid — same payload as direct API webhooks.
  • integration_uninstalled: sent when the partner integration is removed from a merchant’s store.
Each delivery identifies the merchant through id_store (store events) or external_store_id (order events). See Partner Webhooks for configuration and Onboarding Merchants for the end-to-end flow.

​
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:
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).
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 for the link_paid payload.

​
Retry policy

Each delivery attempt has a 5 second timeout, and Wava makes up to 3 attempts roughly a second apart.
  • Connection failures and 5xx responses are retried.
  • 4xx responses are not retried — they are treated as a permanent rejection, so do not return 4xx for a problem on your side that a retry would fix.
  • A 2xx response whose JSON body contains "error": true is recorded as a failure, not a success.
Every attempt is logged with its status, response body and timing, and can be reviewed in the dashboard.
Always respond with 200 immediately, then process the webhook data asynchronously. This prevents timeouts and ensures reliable delivery.