Saltar al contenido principal

Webhooks

Configura webhook al crear la transacción para recibir un POST ante cambios de estado (active / complete / failed). El envío es asíncrono con disparo inmediato (no encolado); latencia típica sub-segundo.

Payload​

{
  "uuid": "422e0ca2-86d1-4a3c-80e6-207061af34c3",
  "transaction_id": "tx-0001",
  "company_id": "201",
  "authorization_method": "kyc_register",
  "active": false,
  "complete": true,
  "failed": false,
  "updated_at": "2026-06-18T15:02:48Z",
  "verification_result": { "selfie_document_match": 96.052 }
}

1. Idempotencia y orden de entrega​

  • Diseña un handler idempotente: procesa una sola vez por uuid + estado.
  • No asumas orden de llegada. Si dudas del estado real, consulta GET /v1/transactions/{uuid} como fuente autoritativa.

2. Reintentos​

BeTrust reintenta solo ante fallos de conexión. Si tu endpoint responde un 5xx, la entrega no se reintenta (no se encola), pero BeTrust registra y alerta el fallo (monitoreo interno). Responde siempre 2xx y procesa de forma asíncrona para no perder eventos.

3. Firma del webhook (roadmap)​

Hoy el webhook no incluye firma. BeTrust puede incorporar verificación de firma (HMAC-SHA256 del cuerpo crudo con un secreto compartido) sin afectar a los clientes ya integrados. Patrón de referencia para cuando esté disponible:

import hmac, hashlib

def firma_valida(cuerpo_crudo: bytes, firma: str, secreto: str) -> bool:
    esperado = hmac.new(secreto.encode(), cuerpo_crudo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, firma)
nota

Firma: roadmap (no presente hoy). Mientras tanto, valida por origen/red y consulta el estado autoritativo con GET.

4. Redirección (alternativa al webhook)​

Con redirect_uri + web_redirect: true, al finalizar se redirige a https://tu-dominio.cl/retorno?id={transaction_id}.

Evitar carreras en el handoff desktop → móvil​

Gatea el avance del canal de origen en el estado autoritativo, no en el "listo" del móvil:

  1. Webhook → backend → habilitar avance.
  2. Polling de respaldo a GET /v1/transactions/{uuid} cada ~1–2 s.
  3. Debounce ~2–3 s antes de habilitar "Continuar".

Ver también: Sandbox y pruebas para testear el handler de webhook.