Webhooks (Callbacks)

Webhooks allow you to be notified in real-time as soon as a block is added to your chain. Here is the complete lifecycle of a webhook.

Webhooks (Callbacks)

Webhooks ermöglichen es Ihnen, in Echtzeit benachrichtigt zu werden, sobald ein Block zu Ihrer Kette hinzugefügt wird. Hier ist der vollständige Lebenszyklus eines Webhooks.

1. Erstellung & Konfiguration

Erstellen Sie den Webhook über die API oder das Dashboard. Sie erhalten dann:

  • Ein **Geheimnis**: wird zum Signieren von Benachrichtigungen verwendet.
  • Eine **Herausforderung**: ein zufälliges Wort (z. B. 'tomato') zur Validierung.
POST /v1/chains/{chainId}/callbacks
{
  "url": "https://votre-api.com/webhook",
  "name": "Serveur Production"
}

2. Validierungs-Handshake

Um den Webhook zu aktivieren, müssen Sie nachweisen, dass Sie die URL kontrollieren. Klicken Sie im Dashboard auf 'Verifizieren', um den Handshake zu starten:

SoWasIt sendet einen **GET**-Aufruf an `{ihre_url}?check=true`.
GET https://votre-api.com/webhook?check=true
Ihr Server muss mit **200 OK** und dem JSON: `{ "challenge": "tomato" }` antworten.
{
  "challenge": "tomato"
}

3. Empfang von Benachrichtigungen

Sobald der Webhook aktiv ist, sendet SoWasIt bei jedem neuen Block einen **POST**-Aufruf.

{
  "event": "block.added",
  "idempotency_key": "uuid-v4",
  "block": {
    "hash": "e3b0c442...",
    "data": { ... }
  }
}

Sicherheit & Signatur

Jede POST-Benachrichtigung enthält Sicherheits-Header, um sicherzustellen, dass der Aufruf von SoWasIt stammt:

  • **X-Callback-Signature**: HMAC-SHA256-Signatur des Anfragetextes (Body), berechnet mit Ihrem Geheimnis.
  • **X-Callback-Secret**: Erinnerung an Ihr Geheimnis (um die Entwicklung zu erleichtern, sollte in der Produktion zugunsten der Signatur ignoriert werden).

Um die Integrität zu überprüfen, berechnen Sie den HMAC-SHA256 des rohen Bodys mit Ihrem Geheimnis neu und vergleichen Sie ihn mit dem Signatur-Header.

// Exemple Node.js / Express
const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-callback-signature'];
  const secret = process.env.SOWASIT_WEBHOOK_SECRET;
  
  // Recalcul du HMAC avec le body brut (raw body)
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(req.body)).digest('hex');
  
  if (signature !== digest) {
    return res.status(401).send('Invalid signature');
  }
  
  // Traitement...
  res.status(200).send('OK');
});
Idempotenz : Jede Benachrichtigung enthält einen `idempotency_key`. Wenn Sie denselben Schlüssel zweimal erhalten (im Falle eines erneuten Versuchs), ignorieren Sie den zweiten Aufruf.

Fehlerbehebung und Protokolle

Wenn Sie Ihre Webhooks nicht empfangen, aktivieren Sie den **Debug-Modus** in Ihrem Dashboard (Menü Logs). Sie können die Details jedes Aufrufversuchs, die von Ihrem Server zurückgegebenen HTTP-Codes sowie eventuelle Signatur- oder Netzwerkfehler einsehen.