¿Qué eventos emite un checkout cripto?

InfraIO Pay dispara un webhook por cada transición de estado. La máquina de estados es deliberadamente pequeña, para que puedas conectar el cumplimiento a exactamente un evento e ignorar el resto.

  • payment.pending, el comprador transmitió la transacción; las confirmaciones todavía se están acumulando.
  • payment.confirmed, la transacción alcanzó el umbral de confirmación de su red.
  • payment.settled, los fondos se barrieron a tu wallet de liquidación. Cumple aquí.
  • session.expired, la ventana de checkout se cerró sin pago. Nunca se cobra.

¿En qué evento deberías cumplir el pedido?

Cumple en payment.settled. Una transacción pending todavía puede fallar en confirmarse, y los umbrales de confirmación varían según la red, así que tratar cualquier estado anterior como definitivo arriesga enviar un pedido contra un pago que nunca llega. La liquidación es el punto en el que el dinero es irreversiblemente tuyo.

Si necesitas mostrarle progreso al comprador, puedes exponer pending y confirmed en tu UI, pero mantén la acción irreversible (enviar, otorgar acceso, mintear) vinculada a settled.

¿Cómo verificas que un webhook es genuino?

Cada webhook se firma con el secreto de tu endpoint. Vuelve a calcular el HMAC sobre el cuerpo crudo de la solicitud y compáralo en tiempo constante con el encabezado de firma; rechaza cualquier cosa que no coincida. Si eres nuevo con HMAC, la referencia de SubtleCrypto.sign de MDN es una buena introducción, y la guía de mejores prácticas de webhooks de Stripe cubre bien el lado operativo.

Verifica antes de parsear o actuar. Una solicitud sin firma o mal firmada nunca debería llegar a tu lógica de negocio.

¿Cómo haces que la entrega sea segura para reintentar?

Los webhooks se entregan al menos una vez (at-least-once), así que el mismo evento puede llegar más de una vez tras un problema de red. Cada evento lleva una clave de idempotencia; registra las claves que ya procesaste y no hagas nada (no-op) ante repeticiones. Responde 2xx rápido y realiza el trabajo lento de forma asíncrona, para que el remitente no agote el tiempo de espera y reintente innecesariamente. InfraIO mantiene un registro de entregas con replay de un clic para las veces que necesites reprocesar deliberadamente.