POST https://api.gotrebol.com/v2/webhooks

{
  "url": "https://tu-app.com/webhooks/trebol",
  "events": ["verification.v2.created", "verification.v2.finished"],
  "description": "Webhook principal de producción"
}

{
  "id": "wh_123",
  "url": "https://tu-app.com/webhooks/trebol",
  "events": ["verification.v2.created", "verification.v2.finished"],
  "status": "enabled",
  "secret": "whsec_XXXXXXXXXXXXXXXXXXXXXXXX",
  "created_at": "2025-08-20T10:00:00Z"
}

{
  "event_name": "verification.v2.finished",
  "data": {
    "verification_id": "5853393e-8cf7-4dc7-afd9-a92df69fff2b",
    "account_id": "212457cc-09bb-4308-b69b-f719e6f2eb03",
    "account_name": "trebol",
    "created_at": "2025-01-15T10:30:00Z",
    "status": "finished",
    "verification_tag": "tu-tag-1234"
  }
}

{
  "event_name": "verification.v2.document_status_updated",
  "data": {
    "verification_id": "5853393e-8cf7-4dc7-afd9-a92df69fff2b",
    "account_id": "212457cc-09bb-4308-b69b-f719e6f2eb03",
    "created_at": "2025-01-15T10:30:00Z",
    "status": "pending",
    "verification_tag": "tu-tag-1234",
    "documents_status": "full_upload",
    "previous_documents_status": "partial_upload",
    "updated_at": "2025-01-15T11:05:27Z"
  }
}

{
  "event_name": "verification.v2.findings.updated",
  "data": {
    "verification_id": "5853393e-8cf7-4dc7-afd9-a92df69fff2b",
    "account_id": "212457cc-09bb-4308-b69b-f719e6f2eb03",
    "findings": [
      {
        "severity": "high",
        "message": "Falta el poder notarial del representante legal",
        "missing_field": "pw_mx"
      },
      {
        "severity": "low",
        "message": "El domicilio del comprobante no coincide con el del acta"
      }
    ],
    "source": "provisional",
    "computed_at": "2025-01-15T11:05:27Z",
    "run_id": "0f6a1c2e-8f1b-4d2a-9c33-5b1f6e2a7d10"
  }
}

{
  "event_name": "verification_item.v2.completed",
  "data": {
    "verification_id": "5853393e-8cf7-4dc7-afd9-a92df69fff2b",
    "item_id": 32644,
    "account_id": "212457cc-09bb-4308-b69b-f719e6f2eb03",
    "account_name": "trebol",
    "item_type": "ac_mx",
    "item_error": "password_protected_pdf",
    "completed_at": "2025-01-15T10:31:42Z",
    "verification_tag": "tu-tag-1234"
  }
}

{
  "event_name": "verification_people.curp_search_completed",
  "data": {
    "verification_id": "c0361bc7-9318-4b09-8186-4ee451cc569f",
    "item_id": 32640,
    "people_id": 3908,
    "people_error": "curp_format_error",
    "people_error_message": "CURP is required and must be a string",
    "account_name": "trebol",
    "account_id": "212457cc-09bb-4308-b69b-f719e6f2eb03",
    "verification_tag": "tu-tag-1234"
  }
}

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

function verifyWebhookSignature(payload, signature, secret) {
  const elements = signature.split(',');
  const timestamp = elements.find(el => el.startsWith('t='))?.split('=')[1];
  const v1 = elements.find(el => el.startsWith('v1='))?.split('=')[1];
  if (!timestamp || !v1) return false;

  const payloadToSign = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payloadToSign, 'utf8')
    .digest('hex');

  const received = Buffer.from(v1, 'hex');
  const expected = Buffer.from(expectedSignature, 'hex');
  if (received.length !== expected.length) return false;
  return crypto.timingSafeEqual(received, expected);
}

const app = express();
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['trebol-signature'];
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Encolar para procesamiento asíncrono
  eventQueue.enqueue(payload);

  // Responder rápido (siempre 2xx si la firma es válida)
  res.status(200).send('OK');
});

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

def verify_webhook_signature(payload: str, signature: str, secret: str) -> bool:
    elements = signature.split(',')
    timestamp = next((e.split('=')[1] for e in elements if e.startswith('t=')), None)
    v1 = next((e.split('=')[1] for e in elements if e.startswith('v1=')), None)
    if not timestamp or not v1:
        return False

    payload_to_sign = f"{timestamp}.{payload}"
    expected = hmac.new(
        secret.encode('utf-8'),
        payload_to_sign.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(v1, expected)

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('Trebol-Signature')
    payload = request.get_data(as_text=True)
    if not verify_webhook_signature(payload, signature, app.config['WEBHOOK_SECRET']):
        abort(401)
    # Encolar para procesamiento asíncrono...
    return 'OK', 200

Mal:  Procesar → guardar en DB → responder 200
Bien: Validar firma → encolar → responder 200 → worker procesa

function getEventId(signatureHeader) {
  // Extrae la firma v1 del header Trebol-Signature
  const elements = signatureHeader.split(',');
  const v1 = elements.find(el => el.startsWith('v1='))?.split('=')[1];
  return v1;
}

const eventId = getEventId(req.headers['trebol-signature']);
if (!eventId) return res.status(400).send('Bad signature');

const ok = await redis.set(`trebol:dedup:${eventId}`, '1', 'EX', 86400, 'NX');
if (!ok) return res.status(200).send('dup'); // ya procesado

const ageSeconds = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10);
if (ageSeconds > 300) return res.status(401).send('Stale signature');

GET /v2/verifications/{verification-id}/people

{
  "external_identities": {
    "curp": {
      "success": true,
      "applicant_data": {
        "curp": "ROMC850315HDFRRS07",
        "names": "CARLOS ALBERTO",
        "first_surname": "RODRIGUEZ",
        "second_surname": "MARTINEZ",
        "birth_date": "1985-03-15",
        "gender": "HOMBRE",
        "nationality": "MEXICO"
      }
    }
  }
}