Sygnet — Webhooks

1. ¿Qué es un webhook? 1. What is a webhook?

Un webhook es una URL de tu servidor a la que Sygnet llama automáticamente cuando ocurre algo. En este caso: cuando emites un certificado nuevo. A webhook is a URL on your server that Sygnet calls automatically when something happens. In this case: when you issue a new certificate.

La diferencia con una API normal es quién inicia la conversación: The difference from a regular API is who starts the conversation:

Es como la diferencia entre llamar al banco para ver si ha llegado una transferencia, o pedir que te manden un SMS cuando llegue. It's like the difference between calling your bank to check if a transfer arrived, or asking them to send you a text when it does.

2. Casos de uso2. Use cases

3. Configurar tu primer webhook 3. Setting up your first webhook

1. 1

   Abre el Dashboard y busca la sección Webhooks Open the Dashboard and find the Webhooks section

   Está justo debajo de las Claves API. It's right below the API Keys section.

2. 2

   Haz clic en + Nuevo e introduce un nombre y tu URL Click + New and enter a name and your URL

   El nombre es solo para ti (ej: pipeline-informes). La URL debe empezar por https://. The name is just for you (e.g. report-pipeline). The URL must start with https://.

3. 3

   Copia el secret que aparece una sola vez Copy the secret shown only once

   Este secret es la contraseña con la que Sygnet firma cada llamada. Si lo pierdes, tendrás que eliminar el webhook y crear uno nuevo. Guárdalo ahora. This secret is the password Sygnet uses to sign every call. If you lose it, you'll need to delete the webhook and create a new one. Save it now.

4. 4

   Emite un certificado desde Sygnet Issue a certificate from Sygnet

   Tu servidor recibirá la llamada en pocos segundos. Comprueba los logs de tu aplicación para ver el payload. Your server will receive the call within seconds. Check your application logs to see the payload.

4. El evento que recibirás 4. The event you will receive

Cuando emites un certificado, Sygnet hace un POST a tu URL con este cuerpo JSON y estas cabeceras: When you issue a certificate, Sygnet sends a POST to your URL with this JSON body and these headers:

Content-Type: application/json
X-Sygnet-Signature: sha256=a3f9b2c1...

{
  "event":         "cert.created",
  "hash":          "a1b2c3d4...",          // SHA3-512, 128 chars
  "sia_level":     1,                      // 1=100% human … 5=100% AI
  "description":   "Q2 2026 Report",       // label you set when certifying, may be null
  "caduca_at":     "2027-06-06T10:00:00",  // expiry date (UTC), null if you didn't set one
  "issued_at":     "2026-06-06T10:00:00Z", // issue date (UTC)
  "published_url": "https://...",          // the URL you passed, or null
  "content_type":  "video"                 // manual or auto-detected from published_url, or null
}

5. Verificar que viene de Sygnet 5. Verifying it comes from Sygnet

Cualquiera podría hacer un POST a tu URL. Para saber que la llamada realmente viene de Sygnet, verifica la firma. Anyone could POST to your URL. To confirm the call really comes from Sygnet, verify the signature.

Cada llamada incluye la cabecera X-Sygnet-Signature: sha256=<valor>. Ese valor es un HMAC-SHA256 calculado sobre el cuerpo completo de la petición usando el secret que guardaste al crear el webhook. Si no coincide, descarta la petición. Every call includes the X-Sygnet-Signature: sha256=<value> header. That value is an HMAC-SHA256 computed over the full request body using the secret you saved when creating the webhook. If it doesn't match, discard the request.

import hmac, hashlib

def verify_signature(body: bytes, header_sig: str, secret: str) -> bool:
    """
    body       → raw request body (bytes, before parsing JSON)
    header_sig → value of X-Sygnet-Signature
    secret     → the secret you copied when creating the webhook
    """
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header_sig)

const crypto = require('crypto');

function verifySignature(body, headerSig, secret) {
  // body must be the raw Buffer or string, not the already-parsed JSON object
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(headerSig)
  );
}

6. Reintentos y desactivación automática 6. Retries and automatic deactivation

# Flask — respuesta mínima aceptableminimum acceptable response
return "", 200

# Express
res.sendStatus(200);

7. Servidor de ejemplo 7. Example server

Los ejemplos siguientes reciben el webhook, verifican la firma y registran el evento. Son el punto de partida mínimo — a partir de aquí añade tu lógica (enviar email, actualizar BD, etc.). The following examples receive the webhook, verify the signature, and log the event. This is the minimal starting point — from here, add your own logic (send email, update DB, etc.).

import hmac, hashlib, json
from flask import Flask, request, abort

app    = Flask(__name__)
SECRET = "your_secret_here"   # the secret you copied from the Dashboard

@app.route("/webhook", methods=["POST"])
def receive():
    body      = request.get_data()          # raw bytes — BEFORE parsing
    signature = request.headers.get("X-Sygnet-Signature", "")
    expected  = "sha256=" + hmac.new(
        SECRET.encode(), body, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        abort(401)                          # invalid signature → reject

    event = json.loads(body)
    print(f"Certificate issued: {event['description']} "
          f"(SIA {event['sia_level']}) — hash: {event['hash'][:16]}…")

    # Add your logic here: send email, log to DB, notify Slack…

    return "", 200


if __name__ == "__main__":
    app.run(port=5000)

const express = require('express');
const crypto  = require('crypto');

const app    = express();
const SECRET = 'your_secret_here';   // the secret you copied from the Dashboard

// Keep raw body BEFORE express parses it as JSON
app.use(express.raw({ type: 'application/json' }));

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-sygnet-signature'] || '';
  const expected  = 'sha256=' + crypto
    .createHmac('sha256', SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    return res.sendStatus(401);    // invalid signature → reject
  }

  const event = JSON.parse(req.body);
  console.log(`Certificate: ${event.description} `+
              `(SIA ${event.sia_level}) — ${event.hash.slice(0,16)}…`);

  // Add your logic here: send email, log to DB, notify Slack…

  res.sendStatus(200);
});

app.listen(3000, () => console.log('Listening on :3000'));

import hmac, hashlib, json, smtplib
from email.mime.text import MIMEText
from flask import Flask, request, abort

app         = Flask(__name__)
SECRET      = "your_secret_here"
SMTP_HOST   = "smtp.gmail.com"
SMTP_PORT   = 587
SMTP_USER   = "you@gmail.com"
SMTP_PASS   = "app_password"
DESTINATION = "client@company.com"
BASE_URL    = "https://mysygnet.com"

def verify(body, sig):
    esp = "sha256=" + hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esp, sig)

SIA_LABELS = {
    1: "100% human authorship",
    2: "Human with AI assist",
    3: "Human-AI co-authorship",
    4: "Mainly AI",
    5: "100% AI generated"
}

def send_email(event):
    hash_  = event["hash"]
    desc   = event.get("description", "—")
    level  = event["sia_level"]
    pdf    = f"{BASE_URL}/api/certificados/{hash_}/pdf"
    verify_url = f"{BASE_URL}/api/certificados/{hash_}"

    sia_label = SIA_LABELS.get(level, f"SIA Level {level}")

    body = f"""Dear client,

A SIA certificate has been issued for the document:

  Document:    {desc}
  Attribution: {sia_label}
  Expires:     {event.get('caduca_at','—')}

Verify its authenticity here:
{verify_url}

Download the official SIA certificate PDF:
{pdf}

Regards,
Sygnet Protocol
"""
    msg = MIMEText(body)
    msg["Subject"] = f"Certificate issued: {desc}"
    msg["From"]    = SMTP_USER
    msg["To"]      = DESTINATION

    with smtplib.SMTP(SMTP_HOST, SMTP_PORT) as s:
        s.starttls()
        s.login(SMTP_USER, SMTP_PASS)
        s.send_message(msg)

@app.route("/webhook", methods=["POST"])
def receive():
    body = request.get_data()
    if not verify(body, request.headers.get("X-Sygnet-Signature", "")):
        abort(401)
    send_email(json.loads(body))
    return "", 200

8. Preguntas frecuentes 8. FAQ