Webhooks

Los webhooks te notifican cuando algo relevante ocurre: un tenant completa su activación, los folios están por agotarse, o un certificado está por vencer.

Agregar endpoint

curl -X POST https://api.example.com/api/v1/webhooks/endpoints \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-app.com/webhooks/facturacion",
    "filterTypes": [
      "tenant.credentials.updated",
      "folio.low",
      "certificate.expiring"
    ]
  }'

await fetch('https://api.example.com/api/v1/webhooks/endpoints', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://tu-app.com/webhooks/facturacion',
    filterTypes: [
      'tenant.credentials.updated',
      'folio.low',
      'certificate.expiring',
    ],
  }),
})

Eventos disponibles

Evento	Descripción	Cuándo se dispara
`tenant.credentials.updated`	Credenciales configuradas	Cuando un tenant completa la activación (certificado + API key)
`folio.low`	Folios bajos	Cuando el stock de folios baja del umbral configurado
`certificate.expiring`	Certificado por vencer	30 días antes del vencimiento del certificado digital
`dte.status.changed`	Estado DTE cambiado	Cuando el SII acepta o rechaza un DTE enviado

Payload

Cada evento envía un POST con este formato:

{
  "event": "tenant.credentials.updated",
  "timestamp": "2024-03-15T14:00:00Z",
  "data": {
    "tenantId": "uuid",
    "apiKey": { "configured": true },
    "certificate": { "configured": true }
  }
}

Verificar firma

Los webhooks incluyen un header webhook-signature que puedes verificar con tu signing secret (disponible en el dashboard).

import crypto from 'crypto'

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('base64')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Reintentos

Los webhooks se entregan con reintentos automáticos (powered by Svix):

5 intentos con backoff exponencial
Si tu endpoint responde con status ≥ 400 o timeout (30s), se reintenta
Puedes ver el historial de entregas en Logs → Webhooks del dashboard

Gestionar endpoints

Listar

curl https://api.example.com/api/v1/webhooks/endpoints \
  -H "Authorization: Bearer sk_live_..."

Eliminar

curl -X DELETE https://api.example.com/api/v1/webhooks/endpoints/{endpointId} \
  -H "Authorization: Bearer sk_live_..."

Ver mensajes

curl https://api.example.com/api/v1/webhooks/messages?limit=20 \
  -H "Authorization: Bearer sk_live_..."

Empezar

Flujos principales

Referencia

Agregar endpoint

Eventos disponibles

Payload

Verificar firma

Reintentos

Gestionar endpoints

Listar

Eliminar

Ver mensajes

​Agregar endpoint

​Eventos disponibles

​Payload

​Verificar firma

​Reintentos

​Gestionar endpoints

​Listar

​Eliminar

​Ver mensajes

Agregar endpoint

Eventos disponibles

Payload

Verificar firma

Reintentos

Gestionar endpoints

Listar

Eliminar

Ver mensajes