Webhooks

Eine Prepaid-API, die „keine Credits mehr“ nur durch einen fehlschlagenden Aufruf meldet, hat in deinem System schon etwas kaputt gemacht. Webhooks sagen dir rechtzeitig Bescheid, solange noch Zeit zum Aufladen ist.

Ereignisse

Einrichtung

1. Füge im Dashboard einen Endpunkt hinzu. Die URL muss https sein (außer localhost zum Testen).
2. Kopiere das Signatur-Secret - wie ein API-Schlüssel wird es nur einmal angezeigt.
3. Klicke auf Test senden und prüfe, dass dein Server mit 2xx antwortet.

Was wir senden

POST https://your-server.example.com/hooks/toolbox
X-ToolBox-Event: credits.low
X-ToolBox-Timestamp: 1700000000
X-ToolBox-Signature: sha256=9f86d081884c7d65...

{
  "id": "0f9b7c1e-...",
  "event": "credits.low",
  "createdAt": "2026-08-16T09:15:00+00:00",
  "data": {
    "balance": 18,
    "threshold": 25,
    "message": "Your credit balance is running low."
  }
}

Die Signatur prüfen

Wer deine Webhook-URL kennt, könnte gefälschte Ereignisse senden - prüfe deshalb jede Zustellung, bevor du darauf reagierst. Die Signatur ist ein HMAC-SHA256 über "{timestamp}.{body}" mit deinem Signatur-Secret:

import crypto from "node:crypto";

function verify(req, secret) {
  const timestamp = req.headers["x-toolbox-timestamp"];
  const signature = req.headers["x-toolbox-signature"];
  const body = req.rawBody; // the RAW string, before JSON.parse

  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${body}`)
    .digest("hex");

  // Constant-time compare - a plain === leaks the correct signature by timing.
  const ok = crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

  // Reject anything older than five minutes so a captured delivery cannot be replayed.
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  return ok && age < 300;
}

Zustellverhalten

• Jede 2xx-Antwort gilt als zugestellt. Alles andere ist ein Fehlschlag.
• Wir warten bis zu 10 Sekunden. Antworte schnell und erledige die Arbeit asynchron - ein langsamer Endpunkt zählt als fehlgeschlagen.
• Nach 20 Fehlschlägen in Folge wird der Endpunkt automatisch deaktiviert, damit wir nicht weiter an eine tote URL senden. Jeder einzelne Erfolg setzt den Zähler zurück.
• Jeder Versuch - Erfolg oder Fehlschlag - steht mit Statuscode und Dauer in deinem Dashboard.
• Ein fehlschlagender Webhook beeinflusst nie deine API-Aufrufe. Zustellungen laufen getrennt von dem Aufruf, den du bezahlt hast.