Skip to Content
Primeros PasosWebhooks y Estados

Resumen de Webhooks

  • Los webhooks notifican a las organizaciones en tiempo casi real sobre cambios en entidades relacionadas (órdenes, contactos, merchants, invitaciones).
  • Puedes configurar múltiples endpoints por organización; todos los endpoints activos reciben todos los eventos.
  • El estado de los eventos se puede inspeccionar a través de la API.

Primeros Pasos

  1. Crea un endpoint con una URL y un secreto.
  2. Almacena tu secreto de forma segura; se usa para firmar cada webhook.
  3. Verifica las firmas en cada solicitud (ver Seguridad más abajo).
  4. Usa Ping para probar tu integración antes de ir a producción.

Gestión de endpoints (ámbito de organización)

  • Crear: POST /organizations/:organizationId/webhooks
  • Listar/obtener: GET /organizations/:organizationId/webhooks[/ :webhookId]
  • Rotar secreto: POST /organizations/:organizationId/webhooks/:webhookId/rotate-secret
  • Pausar/reanudar: POST /organizations/:organizationId/webhooks/:webhookId/(pause|resume)
  • Eliminar: DELETE /organizations/:organizationId/webhooks/:webhookId (eliminación suave)
  • Ping: POST /organizations/:organizationId/webhooks/:webhookId/ping

Los secretos son de solo escritura y nunca se devuelven después de la creación/rotación.

Eventos (APIs de lectura)

  • Listar: GET /organizations/:organizationId/webhook-events
    • Filtros: type, from, to, merchantId, resourceType, resourceId, page, limit
  • Obtener: GET /organizations/:organizationId/webhook-events/:eventId
  • Entregas (estado resumido): GET /organizations/:organizationId/webhook-events/:eventId/deliveries
    • Devuelve entregas por endpoint con deliveryStatus, retryCount, lastRetryAt, lastStatusCode, lastRespondedAt

Replay (ámbito de organización, uso interno por ops o vía permisos):

  • Reenviar un evento: POST /organizations/:organizationId/webhook-events/:eventId/replay
    • Re-encola a todos los endpoints activos (o a un solo endpoint internamente)

Tipos de eventos

Agrupados por familia de recurso. Consulta Webhooks en Profundidad → Tipos de Eventos para la descripción de cada evento y cuándo se dispara.

  • Órdenes: order.created, order.approved, order.processing, order.paid, order.completed, order.failed, order.expired, order.canceled, order.refunded, order.updated
  • Merchants: merchant.created
  • KYB: merchant.kyb.in_progress, merchant.kyb.approved, merchant.kyb.rejected
  • Invitaciones (se emiten para ambos resourceType: invitation y organization_invitation): invitation.created, invitation.accepted, invitation.expired, invitation.failed, invitation.assigned
  • Aprobaciones de políticas: policy.approval.requested, policy.approval.received, policy.approval.approved, policy.approval.rejected
  • Ejecución de políticas (dinámica por tipo de recurso): policy.order.executed, policy.account.executed, policy.deal.executed, policy.user_invite.executed, policy.passkey_enrollment.executed, policy.wallet_access_policy.executed, policy.policy.executed, policy.policy_rule.executed
  • Ingresos bancarios: bank_income.received
  • Sistema: webhook.ping

Sujeto a expansión; los cambios incompatibles se despliegan a través del campo version del payload.

Payload y headers

  • Content type: application/json
  • Estructura del body
{
  "id": "evt_...",
  "type": "order.paid",
  "version": "v1",
  "occurred_at": "2025-08-16T21:52:14.292Z",
  "source": "koywe.api",
  "environment": "production",
  "organization_id": "org_...",
  "merchant_id": "mrc_...",
  "data": { /* específico por tipo */ },
  "relationships": { "self": { "type": "order", "id": "ord_..." } }
}
  • Headers (enviados por Koywe):
    • Koywe-Event-Id, Koywe-Event-Type, Koywe-Event-Version
    • Koywe-Organization-Id, Koywe-Merchant-Id (si aplica)
    • Koywe-Environment
    • Koywe-Webhook-Id
    • Koywe-Signature: HMAC-SHA256 (hex) sobre el body crudo de la solicitud usando el secreto de tu endpoint
    • Koywe-Integrity-Signature: agregado por el servicio de entrega para proteger la integridad en tránsito

Environment es uno de: local | qa | sandbox | production.

Seguridad (verificación de firma)

  • Calcula HMAC-SHA256 del body exacto de la solicitud usando tu secreto de endpoint guardado.
  • Compara tu digest (hex) con Koywe-Signature. Si no coinciden, rechaza el webhook.
  • Seguro contra replays: usa idempotencia por id de evento (el id es estable entre replays).

Pseudo-verificación mínima:

expected = hex(hmac_sha256(secret, raw_body))
if header["Koywe-Signature"] != expected: reject

Comportamiento de entrega y reintentos

  • Al crear un evento, Koywe persiste el evento y encola una entrega por cada endpoint activo.
  • Cada entrega recibe un task id único; puedes consultar el estado resumido a través del endpoint de entregas.
  • Si un endpoint falla, los demás endpoints aún reciben sus entregas.
  • Puedes solicitar un replay para reenviar un evento.

Reglas de reintento:

  • El timeout de la solicitud es de 30 segundos.
  • 5xx, 429, y errores de red / timeouts se reintentan con backoff. Al agotarse el presupuesto de reintentos, la entrega queda marcada como FAILED.
  • Cualquier otro 4xx (400, 401, 403, 404, 422, …) es terminal: la entrega queda marcada como FAILED tras un único intento, sin reintento. Arregla el endpoint y usa el endpoint de replay para reenviar.
  • Devuelve 5xx si quieres reintentos automáticos ante problemas transitorios aguas abajo. Devuelve 429 para señalar throttling — se trata como los demás errores transitorios (se reintenta con backoff) y puede igualmente quedar marcada como FAILED una vez agotado el presupuesto de reintentos.

Mejores prácticas

  • Responde 2xx rápidamente (< 5s); procesa asincrónicamente de tu lado.
  • Valida Koywe-Signature en cada solicitud.
  • Trata los webhooks como entrega al-menos-una-vez; deduplica usando el id del evento.
  • Usa el endpoint de ping para verificar la conectividad después de configurar o rotar el secreto.

Permisos (ámbito de organización)

  • organization_webhooks.manage: crear/actualizar/pausar/reanudar/eliminar/rotar
  • organization_webhooks.view: listar/obtener endpoints
  • organization_webhook_events.view: listar/obtener eventos, ver entregas
  • organization_webhook_events.replay: reenviar eventos

Este resumen complementa la documentación OpenAPI con guía de uso, expectativas de seguridad y taxonomía de eventos.

Last updated on
Guía de PruebasResumen