Webhooks

Per garantir que el webhook és autèntic i enviat per B2Brouter, verifica la signatura inclosa a la capçalera X-B2Brouter-Signature. A continuació s’explica com pots verificar la signatura al teu servidor:

1. Extreure la informació de la capçalera: La capçalera X-B2Brouter-Signature conté dos components:

   • t: El timestamp UNIX quan es va signar el payload.
   • s: La signatura HMAC-SHA256. Exemple de capçalera:

   t=1732530076,s=9f117925ea533a2ea74b19699e03ab5de5664b4ff021d3d01eaff8868ed29e4d

2. Recrear el Payload: Combina el timestamp rebut (t) i el payload JSON en brut (data) usant un punt (.):

   payload = "#{timestamp}.#{data}"

3. Calcular la signatura HMAC-SHA256: Usa la signature_key compartida i el payload per calcular la signatura:

   computed_signature = HMAC-SHA256(signature_key, payload)

4. Comparar les signatures: Compara la computed_signature amb el valor s de la capçalera. Si coincideixen, el webhook és vàlid.

Exemples

1. PHP:

$headers = getallheaders();
$header = $headers['X-B2Brouter-Signature'];

preg_match('/t=([^,]+),s=(.+)/', $header, $matches);

$timestamp = $matches[1];
$signatureHash = $matches[2];

$recalculatedHash = hash_hmac(
  'sha256',
  $timestamp . '.' . file_get_contents('php://input'),
  'your_webhook_secret'
);

$isValid = hash_equals($signatureHash, $recalculatedHash);

Esdeveniments

• ledger.state_change — es dispara quan un ledger (Flux 10 de la DGFiP, Verifactu) canvia d’estat. Consulta Submissió d’un fitxer de Flux 10 per veure la forma del payload i la llista d’estats.

Lliuraments i reintents

Cada esdeveniment genera un lliurament: B2Brouter fa un POST a la URL del webhook amb el payload signat.

• Una resposta 2xx dona el lliurament per fet.
• Si el teu servidor respon 5xx o 429, no respon a temps o no s’hi pot connectar (DNS, connexió, TLS), B2Brouter torna a intentar el lliurament més tard. L’interval entre intents creix a cada intent, i els reintents duren aproximadament una setmana. Aquest termini pot canviar.
• Qualsevol altra resposta 4xx és definitiva: el lliurament no es torna a intentar.

Respon 2xx tan aviat com rebis el webhook i processa l’esdeveniment després. Una resposta lenta compta com un error temporal, i el lliurament es repeteix.

Capçaleres de lliurament

A més de X-B2Brouter-Signature, cada intent porta aquestes capçaleres:

• X-B2Brouter-Delivery-Id: l’identificador del lliurament. És el mateix a tots els intents d’un mateix lliurament.
• X-B2Brouter-Delivery-Attempt: el número de l’intent, començant per 1.

Un mateix lliurament pot arribar més d’una vegada. Fes servir X-B2Brouter-Delivery-Id per descartar els duplicats.

Els lliuraments no arriben sempre en ordre: mentre un lliurament espera el reintent, els esdeveniments posteriors es lliuren igualment. Un webhook avisa que un objecte ha canviat. Abans d’actuar, consulta’n l’estat actual amb l’API.

Registre de webhooks

Al Registre de webhooks, cada lliurament mostra el seu estat i el nombre d’intents:

• Retrying: el lliurament ha fallat i hi ha més intents programats.
• Gave up: s’han esgotat els intents.
• Failed: el teu servidor ha respost amb un error definitiu (4xx).
• Delivered: el lliurament s’ha fet.
• Cancelled: el webhook s’ha desactivat o esborrat abans que el lliurament acabés.

Per repetir un lliurament, obre’l al registre i fes servir Reenviar. Un reenviament porta a X-B2Brouter-Delivery-Attempt el número de l’últim intent. El registre conserva els lliuraments 15 dies.