Webhooks de AAPD
Recibe el evento order.changed y reacciona según el estado de la orden.
AAPD es un producto webhook-driven. La mayor parte del flujo ocurre después de que el paciente sale del widget — el préstamo se aprueba, la ISAPRE se presenta, el 70% se cobra después. Tu integración se entera de cada paso vía webhooks salientes firmados con HMAC-SHA256.
El contrato de los webhooks (eventos, firma, reintentos) vive en Referencia → Webhooks. Esta página cubre el setup y el debugging.
Setup
Cuando se crea tu cuenta provider, Skip registra un webhook_notification_url y genera un webhook_secret. Ambos se configuran server-side en SkipPay.
| Configuración | Qué | Quién la setea |
|---|---|---|
webhook_notification_url | Endpoint HTTPS en tu backend | Equipo Skip, en el onboarding |
webhook_secret | Secreto HMAC-SHA256 para firmar | Equipo Skip — generado y compartido de forma segura |
Puedes pedirle a Skip que actualice la URL en cualquier momento. El secreto se puede rotar; coordínalo con el equipo de Skip.
Qué implementas
Un solo endpoint HTTP que:
- Lee el cuerpo crudo de la request (no parsees JSON antes de chequear la firma).
- Verifica la firma HMAC en
X-Gokeipay-Signaturecontra tuwebhook_secret. Ver Verificación de firma. - Devuelve
200 OKrápido. SkipPay trata cualquier cosa que no sea2xxcomo falla y reintenta — ver Política de retries. - Ramifica según
data.statusy procesa de forma asíncrona (no bloquees la respuesta con trabajo pesado).
Hoy Skip emite un único evento, order.changed, tanto al crear la orden como en cada cambio de estado. El resultado lo lees en data.status — el más importante es paid (orden completamente pagada), y también verás partially_paid, refunded, partially_refunded y cancelled. La lista completa de estados está en el Catálogo de eventos.
Abandono y fallos
Hoy no llega ningún webhook cuando el paciente abandona el flujo a mitad de camino o cuando se rechaza el préstamo: la orden simplemente se queda en pending y no se emite un order.changed nuevo. No esperes una señal push de "fallo".
Para detectar estos casos:
- Por ausencia: si dentro de tu ventana esperada (p. ej. unos minutos tras crear la orden) no recibiste un
order.changedconstatus = paid, trátalo como no-pagado. - Por consulta: consulta el estado de la orden por API en vez de esperar el webhook.
Un evento con nombre propio para rechazo/abandono (order.failed) está en el roadmap; ver Roadmap de eventos granulares.
Replay y debugging
Cuándo pedir replay
- Tu endpoint estuvo caído más de ~2 horas y los retries se acabaron.
- Lanzaste un bug que se comió eventos; necesitas re-procesar las últimas N horas.
- Borraste estado por accidente y necesitas reconstruirlo desde el historial de webhooks.
En los tres casos: pídeselo al equipo de Skip por tu canal de soporte. Skip retiene el historial completo de webhooks por al menos 30 días.
Qué puede hacer el equipo de Skip
- Repetir todos los eventos de una orden específica por
order_hash. - Repetir todos los eventos de tu provider en una ventana de tiempo (úsalo con cuidado — esto puede inundar tu endpoint).
Self-debugging
Si una entrega parece haber fallado pero no sabes por qué:
- Chequea los logs HTTP de tu endpoint para
POSTa tu URL del webhook alrededor del momento esperado. - Si la request llegó, mira el status de la respuesta — cualquier no-2xx cuenta como fallo.
- Si la request no llegó, tu edge / load balancer / firewall puede haberla descartado. El equipo de Skip te puede mostrar el código que vio SkipPay.
Para testear la verificación de firma sin esperar a un evento real, pídele al equipo de Skip un payload + firma de muestra en staging (los replays usan el mismo secreto, así que las firmas siguen calzando).