#Webhooks y eventos

Los webhooks te notifican cuando algo cambia en los datos fiscales de una FiscalEntity: una factura cancelada, una obligación por vencer o un nuevo documento disponible. En lugar de hacer polling, Clarisfy hace un POST a tu endpoint.

#Suscríbete a un endpoint

POST/webhook-endpoints

Registra una URL HTTPS y los eventos que quieres recibir. La respuesta incluye un signing_secret (whsec_…) que usarás para verificar la firma.

#Cuerpo de la petición

Campo	Tipo	Descripción
`url`	string	Requerido. URL HTTPS que recibirá los eventos.
`events`	string[]	Requerido. Tipos de evento a los que te suscribes.
`description`	string	Nota opcional para identificar el endpoint.

curl https://api.clarisfy.com/api/v1/webhook-endpoints \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-app.com/webhooks/clarisfy",
    "events": ["cfdi.canceled", "obligation.due_soon"]
  }'

#Tipos de evento

Evento	Se dispara cuando
`cfdi.received`	Se descarga un nuevo CFDI de la `FiscalEntity`.
`cfdi.canceled`	Un CFDI cambia a estado cancelado en el SAT.
`obligation.due_soon`	Una obligación fiscal está por vencer.
`buzon.message_received`	Llega una notificación o comunicado al Buzón.
`document.available`	Un documento (CSF, 32-D) queda disponible.

#Estructura del payload

Cada entrega es un POST con este envelope:

{
  "id": "evt_1a2b3c4d5e6f7080",
  "type": "cfdi.canceled",
  "created_at": "2026-07-25T18:40:00Z",
  "data": {
    "uuid": "5f2c1a9b-8d3e-4a70-b1c2-9e8f7a6b5c4d",
    "fiscal_entity_id": "fe_9a1c2b3d4e5f6071",
    "canceled_at": "2026-07-25T18:39:12Z"
  }
}

#Verifica la firma

Cada entrega incluye el header Clarisfy-Signature con un timestamp y un HMAC SHA-256 del cuerpo, calculado con tu signing_secret. Verifícalo antes de confiar en el evento.

import crypto from "node:crypto";

/** Verifica la firma HMAC de un webhook de Clarisfy. */
function isValidSignature(rawBody, header, secret) {
  const [ts, sig] = header.split(",").map((p) => p.split("=")[1]);
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Responde 2xx en cuanto recibas el evento. Si tu endpoint falla, Clarisfy reintenta con backoff exponencial durante 24 horas.