Webhooks salientes

Si activas el canal webhook en una vigilancia (plan Pro o Gestoria), Citalto te envia un POST application/json cada vez que se cree un match.

Cabeceras

X-Citalto-Timestamp — epoch en segundos.
X-Citalto-Signature — sha256=<hex> de HMAC_SHA256(secret, "<timestamp>." + body).
User-Agent: Citalto-Webhook/0.1

Tolerancia recomendada: rechaza requests con timestamp fuera de +/-5 minutos para mitigar replays.

Verificacion en Python

import hmac, hashlib, time

CITALTO_SECRET = "..."

def verify(body: bytes, timestamp: str, signature: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = hmac.new(
        CITALTO_SECRET.encode(),
        timestamp.encode() + b"." + body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Cuerpo de la peticion

{
  "event": "match.created",
  "vigilancia": {"id": "...", "name": "Ayudas autonomos", "query": "..."},
  "match": {
    "id": "...",
    "score": 0.149,
    "matched_terms": ["ayudas", "autonomos"],
    "summary_es": "...",
    "created_at": "2026-05-06T08:01:23Z"
  },
  "document": {
    "id": "...",
    "external_id": "BOE-A-2026-9525",
    "source": "boe",
    "title": "Decreto-ley 1/2026...",
    "url": "https://www.boe.es/...",
    "published_at": "2026-05-05T00:00:00Z",
    "metadata": {...}
  }
}

Reintentos: 5 intentos con backoff exponencial (1m, 5m, 15m, 1h, 3h). Tras 5 fallos la entrega queda como failed y puedes reintentarla a mano en /app/deliveries.