Webhooks: recibe un aviso automático cuando el SRI autoriza o rechaza

Para qué sirve

En lugar de consultar el estado una y otra vez, tu sistema puede recibir un aviso (webhook) en el momento en que pasa algo con tus comprobantes. No hay pantalla en el sistema: se configura por la API v2.

Antes de empezar

• Lo configura el dueño de la cuenta (una credencial de vendedor recibe «Los avisos automáticos los configura el dueño de la cuenta.»).
• Necesitas una credencial de la API v2 con el permiso Webhooks.
• Tu URL debe usar https.

Eventos disponibles

• comprobante.autorizado: el SRI autorizó el comprobante.
• comprobante.rechazado: el SRI lo devolvió; el motivo viene en errores.
• comprobante.anulado: la anulación quedó confirmada.
• plan.cupo_bajo: quedan pocos comprobantes en el plan.

Registrar un webhook

1. Envía POST /plataforma/api/v2/webhooks con la cabecera X-Api-Key y en el cuerpo la url y la lista de eventos (si no envías eventos, se suscribe a todos).
2. La respuesta trae un secreto. Guárdalo en ese momento: «Guarde el secreto ahora: no se vuelve a mostrar.»

Otras operaciones:

• GET /webhooks: tus webhooks registrados.
• GET /webhooks/{id}/envios: historial de avisos enviados y sus respuestas.
• DELETE /webhooks/{id}: borrar el webhook.

Verificar que el aviso es auténtico

Cada aviso llega por POST con cabeceras de firma, momento, evento e intento (sus nombres terminan en -Firma, -Momento, -Evento e -Intento). Para verificarlo:

1. Toma el valor de la cabecera de momento y el cuerpo crudo de la petición.
2. Calcula HMAC-SHA256 de momento + "." + cuerpo con tu secreto.
3. Compáralo con la cabecera de firma. Si no coincide, ignora el aviso.

Reintentos

Si tu servidor no responde bien, el sistema reintenta hasta completar 4 intentos: después de 1, 5 y 15 minutos. Responde con un código 2xx en cuanto recibas el aviso y procesa después.

Errores al registrar

• «Falta la URL a la que avisar.»
• «La URL '…' no es válida.»
• «La URL tiene que ser https.»: los avisos llevan datos de tus comprobantes y deben viajar cifrados.
• «El evento '…' no existe. Los que hay: …»: revisa el nombre exacto del evento.