Webhooks empfangen

Der Baustein Webhook schickt bei jedem Alarm ein JSON per POST an deine Adresse. So reagieren eigene Bots, n8n, Zapier oder Home Assistant auf deine Chains. Webhooks gibt es ab dem Plan Pro und in der Testphase.

Die Anfrage

Methode: POST, nur an https-Adressen, ohne Weiterleitungen, Zeitlimit 10 Sekunden.
Adressen im eigenen Netz (localhost, private IP-Bereiche) nimmt Bellchain nicht an.

Content-Type: application/json; charset=utf-8
User-Agent: Bellchain-Webhook/1.0 (+https://bellchain.app)
Bellchain-Event: alert
Bellchain-Delivery: <ID der Zustellung, gleich bei Wiederholungen>
Bellchain-Signature: t=1792243273,v1=9a7a…27cc2

{
  "id": "nEkQk4fzMqjbDEndm0N77E",
  "type": "alert",
  "version": 1,
  "test": false,
  "time": "2026-10-17T12:00:00.000Z",
  "chain": { "id": "chain_456", "name": "BTC Dip-Käufer" },
  "action": "w1",
  "message": "BTC Dip-Käufer: RSI 14: 28,7 · Kurs: 117.234 $",
  "pair": "BTC/USDT",
  "price": 117234,
  "values": [{ "node": "r1", "pin": "out", "label": "RSI 14", "value": 28.7, "text": "28,7" }]
}

id ist für dieselbe Aktion an derselben Kerze immer gleich. Kommt eine Anfrage doppelt an, erkennst du das daran. test ist bei Test-Nachrichten true.

Die Signatur prüfen

Bellchain-Signature enthält den Zeitpunkt t (Sekunden) und v1, einen HMAC-SHA256 über <t>.<Body> mit deinem Signaturschlüssel (whsec_…). So prüfst du in Node.js:

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

export function verify(secret, rawBody, header) {
  const parts = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  // Älter als 5 Minuten: ablehnen, gegen wiederholte Anfragen
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  return parts.v1?.length === expected.length && timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Prüf die Signatur über den unveränderten Body, so wie er ankommt, bevor du ihn als JSON liest.

Antworten und Wiederholungen

Antworte mit einem Status 2xx, sobald du die Anfrage angenommen hast. Bei 408, 425, 429, 5xx oder Netzwerkfehlern versucht Bellchain es erneut, insgesamt fünfmal: sofort, nach etwa 5 Sekunden, 25 Sekunden, 2 Minuten und 10 Minuten. Nennst du mit Retry-After eine Wartezeit, gilt mindestens diese. Andere 4xx-Antworten und Weiterleitungen gelten als endgültig gescheitert.

Stummschaltungen gelten nicht für Webhooks: Sie laufen weiter, damit deine Automatisierung nichts verpasst.