Webhooks

El contrato de eventos y la firma Notta-Signature para reaccionar a cambios de estado de un DTE sin polling.

Suscribite a eventos para reaccionar en tiempo real cuando un DTE cambia de estado, en vez de pollear.

Estado actual

El contrato de webhooks (eventos + firma Notta-Signature) está definido y es estable: programa tu consumer contra él desde ahora. El endpoint de suscripción POST /api/v1/webhooks aún no está habilitado — suscribite cuando se active. Mientras tanto consulta el estado con GET /api/v1/dtes/:id (ver Referencia API de DTEs).

Suscripción (contrato objetivo)

Así se va a ver la suscripción cuando el endpoint se habilite — hoy esta request responde 404:

curl -X POST https://app.notta.cl/api/v1/webhooks \
  -H "Authorization: Bearer ntt_cert_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://tuapp.com/webhooks/notta",
    "events": ["dte.emitted", "dte.status_changed", "dte.rejected"]
  }'

Tipos de evento

Evento	Cuándo
`dte.emitted`	El DTE fue firmado y encolado al SII
`dte.status_changed`	El estado SII cambió (p. ej. `queued` → `EPR`)
`dte.accepted`	El SII aceptó el DTE (`EPR`, terminal)
`dte.rejected`	El SII rechazó el DTE (`RFR`/`RCT`/`RSC` — ver Catálogo de errores)

Payload

{
  "id": "evt_01957a91-...",
  "type": "dte.status_changed",
  "created_at": "2026-05-13T14:33:02.000Z",
  "data": {
    "dte_id": "01957a91-0b50-7000-8000-000000000001",
    "tipo_dte": 33,
    "folio": 1234,
    "sii_status": "EPR"
  }
}

Verificación de firma

Cada entrega incluye un header Notta-Signature con un HMAC-SHA256 del cuerpo crudo, firmado con tu webhook secret. Verifica la firma antes de confiar en el payload:

import { createHmac, timingSafeEqual } from "node:crypto";
 
function verify(rawBody: string, signature: string, secret: string): boolean {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

De dónde sale el secret

El webhook secret se va a entregar una sola vez en la respuesta de la creación de la suscripción (POST /api/v1/webhooks). Guárdalo en tu secret manager en ese momento: no va a ser recuperable después, solo rotable.

Reintentos de entrega

La policy de reintentos (cantidad, backoff, ventana de deadletter) se va a documentar aquí cuando la entrega saliente se habilite. Hasta entonces, diseñá tu handler idempotente por id de evento: cualquier policy de entrega implica que un mismo evento puede llegar más de una vez.

Próximos pasos

Referencia API de DTEs — GET /dtes/:id y POST /dtes/:id/refresh-status, el camino para seguir el estado hoy.
Catálogo de errores — los rechazos SII que vas a recibir en dte.rejected.
Agentes — patrones para que un agente LLM reaccione a los eventos.
Límites de tasa — el patrón de backoff si sigues el estado por polling.