Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos en tu cuenta de Orangepill. Los webhooks son callbacks HTTP enviados a tu servidor.

Qué hacen los webhooks

• Te notifican cuando los pagos tienen éxito o fallan
• Te alertan sobre cambios en el saldo de la wallet
• Rastrean eventos del journey del cliente
• Disparan flujos de trabajo automatizados

Configuración rápida

curl https://api.orangepill.cloud/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/orangepill",
    "events": [
      "payment.succeeded",
      "payment.failed",
      "wallet.balance_updated",
      "customer.created"
    ]
  }'

Ejemplo de payload de webhook

{
  "id": "evt_abc123",
  "type": "payment.succeeded",
  "created": 1642080000,
  "data": {
    "id": "preq_xyz789",
    "amount": 50000,
    "currency": "COP",
    "status": "succeeded",
    "payment_method": "bre_b",
    "metadata": {
      "order_id": "order_123"
    }
  }
}

Verifica firmas de webhook

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Eventos disponibles

Pagos

• payment.succeeded - Pago completado con éxito
• payment.failed - Pago fallido o declinado
• payment.pending - Pago pendiente de confirmación
• payment.refunded - Pago reembolsado

Wallets

• wallet.created - Nueva wallet creada
• wallet.balance_updated - Saldo cambiado
• wallet.transaction_created - Nueva transacción

Clientes

• customer.created - Nuevo registro de cliente
• customer.updated - Datos del cliente cambiados

Comportamiento de reintentos

• Los webhooks fallidos se reintentan con backoff exponencial
• Máximo 3 intentos de reintento
• 1 minuto, 5 minutos, 15 minutos

Pruebas de webhooks

Usa herramientas para probar webhooks:

• webhook.site
• ngrok para desarrollo local
• Logs de webhook en el dashboard de Orangepill

Próximos pasos

• Primeros Pasos - Conceptos básicos de la API
• Ejemplos - Manejadores de webhook de muestra
• SDKs - Helpers para verificación de webhooks