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)

Les webhooks vous permettent d'être notifié en temps réel dès qu'un bloc est ajouté à votre chaîne. Voici le cycle de vie complet d'un webhook.

1. Création & Configuration

Créez le webhook via l'API ou le Dashboard. Vous recevrez alors :

  • Un **Secret** : utilisé pour signer les notifications.
  • Un **Challenge** : un mot aléatoire (ex: 'tomato') pour la validation.
POST /v1/chains/{chainId}/callbacks
{
  "url": "https://votre-api.com/webhook",
  "name": "Serveur Production"
}

2. Handshake de Validation

Pour activer le webhook, vous devez prouver que vous contrôlez l'URL. Cliquez sur 'Vérifier' dans le dashboard pour lancer le handshake :

SoWasIt envoie un **GET** sur `{votre_url}?check=true`.
GET https://votre-api.com/webhook?check=true
Votre serveur doit répondre **200 OK** avec le JSON : `{ "challenge": "tomato" }`.
{
  "challenge": "tomato"
}

3. Réception des Notifications

Une fois actif, SoWasIt envoie un **POST** à chaque nouveau bloc.

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

Sécurité & Signature

Chaque notification POST inclut des headers de sécurité pour garantir que l'appel provient bien de SoWasIt :

  • **X-Callback-Signature** : Signature HMAC-SHA256 du corps (body) de la requête, calculée avec votre secret.
  • **X-Callback-Secret** : Rappel de votre secret (pour faciliter le développement, à ignorer en production au profit de la signature).

Pour vérifier l'intégrité, recalculez le HMAC-SHA256 du body brut avec votre secret et comparez-le au header signature.

// 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');
});
Idempotence : Chaque notification inclut un `idempotency_key`. Si vous recevez deux fois la même clé (en cas de retry), ignorez le second appel.

Débogage et Logs

Si vous ne recevez pas vos webhooks, activez le **Mode Debug** dans votre tableau de bord (menu Logs). Vous pourrez visualiser le détail de chaque tentative d'appel, les codes HTTP renvoyés par votre serveur et les éventuelles erreurs de signature ou de réseau.