Troubleshooting de webhooks

”No recibo webhooks”

Debe verificarse lo siguiente:

1. La API key tiene webhookUrl configurada (solicitar confirmación al administrador).
2. La URL es HTTPS y resuelve a una IP pública válida (no RFC1918 ni link-local).
3. El endpoint responde con 2xx en menos de 10 s.
4. El comprobante se emitió vía API: los emitidos desde el POS web no disparan webhooks.
5. Hacienda ya respondió. Si el comprobante está en procesando, todavía no hay nada que notificar.

”Recibo 401 o firma inválida”

Debe verificarse lo siguiente:

1. Se utiliza el mismo webhookSecret que se generó al crear o rotar la key.
2. Se lee el body crudo antes de parsearlo (sin re-serializar el JSON).
3. La comparación se realiza con una función timing-safe (timingSafeEqual, hmac.compare_digest, hash_equals, etc.).
4. No se agregan ni se eliminan espacios, BOM ni newlines del body antes del HMAC.

”Recibo el mismo evento varias veces”

Es un comportamiento esperado durante un reintento. Debe implementarse la deduplicación por nonce: el nonce cambia en cada intento, por lo que sirve como clave única de “envío”.

”Recibí webhook pero el comprobante no aparece en GET /facturas/{clave}”

Es improbable, pero puede ocurrir por una race condition. Debe reintentarse el GET con backoff exponencial. Si la situación persiste por más de un minuto, debe abrirse un ticket de soporte.