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 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:
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

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.
Always respond with 200 immediately, then process the webhook data asynchronously. This prevents timeouts and ensures reliable delivery.