Cómo verificar los webhooks de facturación electrónica de forma segura

Los webhooks te avisan al instante cuando el SRI autoriza, rechaza o se anula un comprobante. Pero tu URL es pública: cualquiera podría enviarle mensajes falsos. Por eso hay que verificar la firma de cada aviso.

Cómo firma AZUR los avisos

Cada aviso llega con dos cabeceras:

• X-Azur-Momento: el momento del envío.
• X-Azur-Firma: HMAC-SHA256 de momento + "." + cuerpo_crudo con tu secreto.

El secreto te lo da AZUR al registrar el webhook (se muestra una sola vez).

Cómo verificar

1. Lee el cuerpo crudo, tal cual llegó. No uses el JSON ya decodificado y vuelto a convertir: cambiaría los bytes.
2. Calcula el HMAC-SHA256 de momento + "." + cuerpo con tu secreto.
3. Compáralo con X-Azur-Firma usando una comparación en tiempo constante.
4. Si no coincide, responde con error e ignora el aviso.

En PHP:

$momento = $_SERVER['HTTP_X_AZUR_MOMENTO'] ?? '';
$firma = $_SERVER['HTTP_X_AZUR_FIRMA'] ?? '';
$cuerpo = file_get_contents('php://input');
$esperada = hash_hmac('sha256', $momento . '.' . $cuerpo, $secreto);
if (!hash_equals($esperada, $firma)) { http_response_code(401); exit; }

Los SDK oficiales lo hacen por ti: Azur\Sdk\Webhook::verificar() en PHP y verificarWebhook() en JavaScript.

Responde rápido

Devuelve un código 2xx en cuanto verifiques la firma y procesa el evento en segundo plano. Si tu servidor falla o no contesta, AZUR reintenta a 1, 5 y 15 minutos.

Procesa cada evento una sola vez

Por los reintentos, un mismo aviso puede llegar más de una vez. Usa la clave de acceso del comprobante junto con el tipo de evento para no procesarlo dos veces.

Otras buenas prácticas

• Usa siempre https.
• Guarda el secreto en variables de entorno.
• Si sospechas que el secreto se filtró, elimina el webhook y créalo de nuevo.
• Registra los avisos rechazados para detectar intentos de abuso.

Encuentra los detalles de cada evento en la guía de la API y en la referencia completa.

Conecta tus avisos: crea tu cuenta gratis.