Webhooks
Cada cambio llega a tu sistema. Firmado y sin duplicados.
Factuarea avisa a tu servidor cuando una factura cambia, se cobra o falla. Si no contestas, vuelve a intentarlo automáticamente.
- Firma HMAC-SHA256
- Ocho intentos durante más de 4 días
- Reenvío de entregas
Integraciones y formatos compatibles
WhatsApp
FactuareaTu servidor
POST /webhook
200 OK
El evento sale firmado. Si la entrega se repite, conserva el mismo identificador para que la proceses una sola vez.
Firmado
HMAC-SHA256
Deduplicación
Event-Id estable
8 intentos
backoff + jitter
Verificar la firma
Verificación HMAC-SHA256 en cuatro pasos
La cabecera Factuarea-Signature trae el instante de la entrega y el HMAC-SHA256 de t.cuerpo calculado con tu secreto. Verificarla es fácil; verificarla mal, más fácil todavía.
- 1
Firma sobre el cuerpo crudo
El HMAC se calcula sobre los bytes que llegaron, no sobre el JSON que tu framework ya parseó y volvió a serializar.
- 2
Compara en tiempo constante
timingSafeEqual, hash_equals o lo que traiga tu lenguaje para comparar sin filtrar por dónde falla.
- 3
Mira el reloj
La cabecera trae t con el instante UNIX de la entrega. Rechaza si han pasado más de 300 segundos.
- 4
Acepta cualquiera de los v1
Durante las 24 horas siguientes a una rotación la cabecera trae dos firmas. Basta con que cuadre una.
Node · el verificador entero
import { createHmac, timingSafeEqual } from "node:crypto"; // `cuerpo` son los BYTES que llegaron, sin parsear ni volver a serializar.export function firmaValida(cuerpo, cabecera, secreto) { const partes = cabecera.split(",").map((p) => p.split("=")); const t = Number(partes.find(([clave]) => clave === "t")?.[1]); const firmas = partes.filter(([clave]) => clave === "v1").map(([, v]) => v); // Ventana de 5 minutos: una entrega capturada no vale para mañana. if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; const esperada = createHmac("sha256", secreto) .update(`${t}.${cuerpo}`) .digest("hex"); // Durante una rotación llegan dos v1. Basta con que cuadre uno. return firmas.some( (firma) => firma.length === esperada.length && timingSafeEqual(Buffer.from(firma), Buffer.from(esperada)) );}Cuando tu servidor no contesta
Si tu servidor cae, volvemos a llamar
Cada evento llega firmado y conserva el mismo identificador. Así puedes reintentarlo sin procesarlo dos veces.
- Cualquier respuesta 2xxEntrega cerrada. Se guardan el código y el tiempo que tardaste, y ahí se acaba.
- 408, 425 y 429Son los únicos 4xx transitorios y sí se reintentan. El resto de 4xx se marca como fallo permanente para que corrijas la petición y la reenvíes después.
- 5xx, timeout o silencioA la cola. Ocho intentos en total, con esperas que crecen: el primer reintento al minuto, el último tres días después.
Firmado
HMAC-SHA256
Deduplicación
Event-Id estable
8 intentos
backoff + jitter
Rotar el secreto
Rotación de secreto con 24 horas de transición
El secreto en claro se enseña una sola vez, al crear el endpoint y al rotarlo. Después se guarda cifrado para firmar entregas y también como hash para verificarlo. Rotarlo no corta nada si respetas el orden.
Secreto anterior
Secreto nuevo
Durante la ventana cada entrega sale firmada dos veces: la cabecera trae t, el v1 del secreto nuevo y el v1 del anterior. Tu verificador da la firma por buena si cuadra cualquiera de los dos.
El orden que no pierde un evento
- 1
Haz que tu servidor acepte los dos secretos a la vez.
- 2
Rota, y guarda el nuevo: solo se enseña una vez.
- 3
Despliega el nuevo secreto en tu servidor.
- 4
Antes de que pasen 24 horas, retira el viejo.
No se puede rotar dos veces en cinco minutos
Es un guardarraíl a propósito. Dos rotaciones seguidas dejarían fuera el secreto que tu servidor acaba de aprender, y ahí sí se caen entregas.
Rotación y doble firma, en la guíaSuperficie publicada
Una integración que encaja con tu stack
El contrato OpenAPI, los SDK y el servidor MCP parten de la misma API. Las cifras se revisan contra la superficie publicada para que puedas evaluar alcance y mantenimiento antes de integrar.
- operaciones API
- 413
- recursos
- 37
- herramientas MCP
- 391
- páginas de documentación
- 797
Tecnologías y clientes compatibles
Stripe
TypeScript
PHP
OpenAPI
Los logotipos identifican tecnologías o clientes compatibles; no implican una relación comercial ni un testimonio.
Antes de ponerlo en producción
Dudas habituales sobre webhooks
Verifica la cabecera Factuarea-Signature con HMAC-SHA256, el cuerpo sin modificar y una tolerancia de cinco minutos. Los SDK oficiales incluyen el verificador para evitar diferencias de serialización.
Coge una clave de prueba y manda un ping
El circuito entero (crear el endpoint, firmar, fallar, reintentar, reenviar) se prueba en sandbox sin tocar nada real. La clave de prueba se saca del panel en un minuto.