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. You receive webhooks for order status changes (confirmed, cancelled, refunded, failed).

​
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 updated (same payload as direct API webhooks).
  • Store onboarding webhooks: Sent to the partner when a new store is onboarded on their platform (e.g., store activated, store configuration updated).

​
Webhook payload

When an order status changes, Wava sends a POST request to your webhook URL: 
{
  "event": "order.confirmed",
  "data": {
    "id_order": 12345,
    "id_external": "order-12345",
    "status": "confirmed",
    "amount": 50000,
    "currency": "COP",
    "payment_gateway": "nequi",
    "created_at": "2025-01-18T10:30:00.000Z",
    "confirmed_at": "2025-01-18T10:31:15.000Z"
  }
}

​
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.