Troubleshooting de webhooks

”No recibo webhooks”

Verificá:

1. ✅ La API key tiene webhookUrl configurada (pedile al admin que confirme).
2. ✅ La URL es HTTPS y resuelve a una IP pública válida (no RFC1918 ni link-local).
3. ✅ Tu endpoint responde con 2xx y 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”

Verificá:

1. ✅ Usás el mismo webhookSecret que se generó al crear o rotar la key.
2. ✅ Leés el body crudo antes de parsearlo (no re-serialices el JSON).
3. ✅ Comparás con una función timing-safe (timingSafeEqual, hmac.compare_digest, hash_equals, etc.).
4. ✅ No agregás ni quitás espacios, BOM ni newlines al body antes del HMAC.

”Recibo el mismo evento varias veces”

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

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

Improbable, pero puede ocurrir por una race condition. Reintentá el GET con backoff exponencial. Si persiste por más de un minuto, abrí un ticket de soporte.