Webhooks
Cada canvi arriba al teu sistema. Signat i sense duplicats.
Factuarea avisa el teu servidor quan una factura canvia, es cobra o falla. Si no contestes, ho torna a provar automàticament.
- Signatura HMAC-SHA256
- Vuit intents durant més de 4 dies
- Reenviament de lliuraments
Integracions i formats compatibles
WhatsApp
FactuareaEl teu servidor
POST /webhook
200 OK
L'esdeveniment surt signat. Si el lliurament es repeteix, conserva el mateix identificador perquè només el processis una vegada.
Signat
HMAC-SHA256
Deduplicació
Event-Id estable
8 intents
backoff + jitter
Verificar la signatura
Verificació HMAC-SHA256 en quatre passos
La capçalera Factuarea-Signature porta l'instant del lliurament i l'HMAC-SHA256 de t.cos calculat amb el teu secret. Verificar-la és fàcil; verificar-la malament, encara més.
- 1
Signa sobre el cos cru
L'HMAC es calcula sobre els bytes que han arribat, no sobre el JSON que el teu framework ja ha analitzat i ha tornat a serialitzar.
- 2
Compara en temps constant
timingSafeEqual, hash_equals o el que porti el teu llenguatge per comparar sense filtrar per on falla.
- 3
Mira el rellotge
La capçalera porta t amb l'instant UNIX del lliurament. Rebutja si han passat més de 300 segons.
- 4
Accepta qualsevol dels v1
Durant les 24 hores següents a una rotació la capçalera porta dues signatures. N'hi ha prou que en quadri una.
Node · el verificador sencer
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)) );}Quan el teu servidor no contesta
Si el teu servidor cau, tornem a trucar
Cada esdeveniment arriba signat i conserva el mateix identificador. Així el pots reintentar sense processar-lo dues vegades.
- Qualsevol resposta 2xxLliurament tancat. Es guarden el codi i el temps que has trigat, i aquí s'acaba.
- 408, 425 i 429Són els únics 4xx transitoris i sí que es reintenten. La resta de 4xx es marca com a error permanent perquè corregeixis la petició i la reenviïs després.
- 5xx, timeout o silenciA la cua. Vuit intents en total, amb esperes que creixen: el primer reintent al minut, l'últim tres dies després.
Signat
HMAC-SHA256
Deduplicació
Event-Id estable
8 intents
backoff + jitter
Rotar el secret
Rotació del secret amb 24 hores de transició
El secret en clar s'ensenya un sol cop, en crear l'endpoint i en rotar-lo. Després es desa xifrat per signar lliuraments i també com a hash per verificar-lo. La rotació no talla res si respectes l'ordre.
Secret anterior
Secret nou
Durant la finestra cada lliurament surt signat dues vegades: la capçalera porta t, el v1 del secret nou i el v1 de l'anterior. El teu verificador dona la signatura per bona si en quadra qualsevol dels dos.
L'ordre que no perd cap esdeveniment
- 1
Fes que el teu servidor accepti els dos secrets alhora.
- 2
Rota, i desa el nou: només s'ensenya un cop.
- 3
Desplega el secret nou al teu servidor.
- 4
Abans que passin 24 hores, retira el vell.
No es pot rotar dues vegades en cinc minuts
És una barana posada expressament. Dues rotacions seguides deixarien fora el secret que el teu servidor acaba d'aprendre, i llavors sí que cauen lliuraments.
Rotació i doble signatura, a la guiaSuperfície publicada
Una integració que encaixa amb el teu stack
El contracte OpenAPI, els SDK i el servidor MCP parteixen de la mateixa API. Les xifres es revisen contra la superfície publicada perquè puguis avaluar l'abast i el manteniment abans d'integrar.
- operacions API
- 413
- recursos
- 37
- eines MCP
- 391
- pàgines de documentació
- 797
Tecnologies i clients compatibles
Stripe
TypeScript
PHP
OpenAPI
Els logotips identifiquen tecnologies o clients compatibles; no impliquen una relació comercial ni un testimoni.
Abans de posar-ho en producció
Dubtes habituals sobre webhooks
Verifica la capçalera Factuarea-Signature amb HMAC-SHA256, el cos sense modificar i una tolerància de cinc minuts. Els SDK oficials inclouen el verificador per evitar diferències de serialització.
Agafa una clau de prova i envia un ping
El circuit sencer (crear l'endpoint, signar, fallar, reintentar, reenviar) es prova en sandbox sense tocar res real. La clau de prova se treu del tauler en un minut.