Die API und die drei Werkzeuge, die daran andocken

Der Umschlag, bei allen fünf derselbe

{
  "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"
    }
  }
}

Der Inhalt ändert sich mit dem Ereignis; der Umschlag nicht. Die Kennung ändert sich zwischen Wiederholungen nicht, ein Duplikat zu verwerfen ist auf Ihrer Seite also eine einzige Bedingung.

Die Kopfzeilen jeder Zustellung

Die Signatur prüfen

Die Signatur ist HMAC-SHA256 über den Zeitstempel, einen Punkt und den rohen, nicht geparsten Rumpf. Dasselbe Format, das die Zahlungsanbieter verwenden, also das, das Sie vermutlich schon einmal geschrieben haben.

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;
}

Vergleichen Sie in konstanter Zeit und weisen Sie alles ab, dessen Zeitstempel älter als ein paar Minuten ist. Ohne diese zweite Prüfung kann Ihnen eine Kopie einer alten Zustellung jahrelang erneut geschickt werden, und die Signatur stimmt weiterhin.

Wiederholungen, Pause und warum nichts ankommt

• Jede 2xx-Antwort genügt. Wir lesen den Rumpf nicht: antworten Sie schnell und arbeiten Sie danach, denn nach zehn Sekunden geben wir auf, und das zählt als Fehlschlag.
• Sechs Versuche mit wachsender Wartezeit — eine Minute, fünf, fünfzehn, eine Stunde, drei und sechs — verteilt über etwa zehneinhalb Stunden. Das deckt ein nächtliches Deployment und eine Wartung am Wochenende ab.
• Dreißig Fehlschläge hintereinander pausieren die Adresse, und der Grund wird festgehalten. Aufgehoben wird die Pause, indem man sie wieder auf aktiv setzt, was auch den Zähler zurücksetzt.
• Wir rufen nur öffentliche https-Adressen an. Geprüft wird beim Registrieren und noch einmal vor jeder Zustellung, denn ein Name, der heute ins öffentliche Internet auflöst, kann morgen in Ihr internes Netz auflösen.
• Eine heute registrierte Adresse bekommt nicht das von gestern: ein Abonnement zählt ab seiner Anlage, damit das erste Szenario nicht sofort vierzig Ausführungen auslöst.