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)

Los webhooks le permiten recibir notificaciones en tiempo real cuando ocurren eventos en sus cadenas, como la adición de un nuevo bloque. Aquí está el ciclo de vida completo de un webhook.

1. Creación y Configuración

Cree el webhook a través de la API o el Dashboard. Luego recibirá:

  • Un **Secreto**: utilizado para firmar las notificaciones.
  • Un **Desafío**: una palabra aleatoria (ej: 'tomato') para la validación.
POST /v1/chains/{chainId}/callbacks
{
  "url": "https://votre-api.com/webhook",
  "name": "Serveur Production"
}

2. Handshake de Validación

Para activar el webhook, debe demostrar que controla la URL. Haga clic en 'Verificar' en el dashboard para iniciar el handshake:

SoWasIt envía un **GET** a `{su_url}?check=true`.
GET https://votre-api.com/webhook?check=true
Su servidor debe responder **200 OK** con el JSON: `{ "challenge": "tomato" }`.
{
  "challenge": "tomato"
}

3. Recepción de Notificaciones

Una vez activo, SoWasIt envía un **POST** por cada nuevo bloque.

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

Seguridad y Firma

Cada notificación POST incluye encabezados de seguridad para garantizar que la llamada provenga de SoWasIt:

  • **X-Callback-Signature**: firma HMAC-SHA256 del cuerpo (body) de la solicitud, calculada con su secreto.
  • **X-Callback-Secret**: recordatorio de su secreto (para facilitar el desarrollo, debe ignorarse en producción en favor de la firma).

Para verificar la integridad, recalcule el HMAC-SHA256 del cuerpo bruto con su secreto y compárelo con el encabezado de firma.

// 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');
});
Idempotencia : Cada notificación incluye una `idempotency_key`. Si recibe la misma clave dos veces (en caso de reintento), ignore la segunda llamada.

Depuración y Registros

Si no está recibiendo sus webhooks, active el **Modo Depuración** en su panel de control (menú Logs). Podrá ver los detalles de cada intento de llamada, los códigos HTTP devueltos por su servidor y cualquier error de firma o de red.