L'API e i tre strumenti con cui si collega

La busta, uguale per tutti e cinque

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "type": "announcement.published",
  "occurred_at": "2026-09-01T06:00:00.000Z",
  "organization_id": "0a9b8c7d-6e5f-4a3b-8c9d-0e1f2a3b4c5d",
  "data": {
    "announcement": {
      "id": "6b1f0f1e-0c2a-4c5e-9a3d-2f5b8c7d1e40",
      "title": "Parada de la línea 3 el jueves",
      "body": "El jueves 4 a las 06:00 para la línea 3 por mantenimiento programado.",
      "kind": "news",
      "language": "es",
      "requires_acknowledgement": true,
      "audience": {
        "type": "departments",
        "names": [
          "Mantenimiento",
          "Calidad"
        ]
      },
      "community": "Planta de Getafe",
      "author": {
        "id": "3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c",
        "name": "Ana García",
        "email": "ana.garcia@empresa.com",
        "external_id": "EMP-0042"
      },
      "url": "https://app.blastack.com/inicio#post-6b1f0f1e-0c2a-4c5e-9a3d-2f5b8c7d1e40",
      "status": "published"
    }
  }
}

Quello che c'è dentro cambia con l'evento; la busta no. L'identificativo non cambia tra un tentativo e l'altro, quindi scartare un doppione è una condizione di una riga dalla vostra parte.

Le intestazioni di ogni invio

Verificare la firma

La firma è un HMAC-SHA256 sulla marca temporale, un punto e il corpo grezzo, non interpretato. È lo stesso formato che usano i gestori di pagamento, cioè quello che con ogni probabilità avete già scritto una volta.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, headers, secret) {
  const sent = headers["blastack-signature"] ?? "";
  const t = /t=(\d+)/.exec(sent)?.[1];
  const v1 = /v1=([0-9a-f]+)/.exec(sent)?.[1];
  if (!t || !v1) return false;

  const mine = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`, "utf8")
    .digest("hex");

  if (v1.length !== mine.length) return false;
  if (!timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(mine, "hex"))) {
    return false;
  }
  return Math.abs(Date.now() / 1000 - Number(t)) < 300;
}

Confrontate a tempo costante e rifiutate tutto ciò che ha una marca temporale di più di qualche minuto. Senza quella seconda verifica, una copia di un invio vecchio può esservi rispedita per anni e la firma continuerà a risultare valida.

Ritentativi, pausa e perché non arriva niente

• Va bene qualsiasi risposta 2xx. Non leggiamo il corpo: rispondete in fretta e fate il lavoro dopo, perché dopo dieci secondi rinunciamo e vale come un errore.
• Sei tentativi con attesa crescente — un minuto, cinque, quindici, un'ora, tre e sei — distribuiti su circa dieci ore e mezza. Copre il rilascio notturno e la manutenzione del fine settimana.
• Trenta errori di fila mettono in pausa l'indirizzo, e il motivo resta scritto. Si toglie rimettendolo su attivo, cosa che azzera anche il contatore.
• Chiamiamo solo indirizzi https pubblici. Si verifica al momento della registrazione e di nuovo prima di ogni invio, perché un nome che oggi risolve verso internet pubblico domani può risolvere verso la vostra rete interna.
• Un indirizzo registrato oggi non riceve quelli di ieri: un abbonamento conta da quando viene creato, perché montare il primo scenario non faccia partire quaranta esecuzioni in una volta.