Webhooks · DiFACT Docs

Cómo funcionan

Registrás una URL en tu servidor. Cuando SIFEN procesa un documento, DiFACT envía un POST a esa URL con el payload del evento. Tu servidor debe responder con 2xx en menos de 5 segundos. Si falla, reintentamos hasta 5 veces con backoff exponencial.

Usá la librería difact-js o verificá la firma X-DiFACT-Signature manualmente para validar que el evento es auténtico antes de procesarlo.

Eventos disponibles

Evento	Descripción
`factura.approved`	SIFEN aprobó el documento. Ya tiene validez tributaria.
`factura.rejected`	SIFEN rechazó el documento. El campo `sifen_errors` detalla los motivos.
`factura.cancelled`	El documento fue anulado exitosamente.
`factura.pending_retry`	SIFEN no respondió. DiFACT reintentará automáticamente.

Registrar un webhook

POST/v1/webhooksCrear webhook

Body

urlreqstring URL HTTPS de tu servidor.

eventsreqarray Lista de eventos a escuchar. Usá ["*"] para todos.

descriptionopcstring Nombre descriptivo para identificar el webhook en el panel.

{
  "url": "https://tu-sistema.com/webhooks/difact",
  "events": ["factura.approved", "factura.rejected"],
  "description": "ERP producción"
}

GET/v1/webhooksListar webhooks

Retorna todos los webhooks activos de tu cuenta.

DELETE/v1/webhooks/:idEliminar webhook

Elimina permanentemente el webhook. Las peticiones en vuelo no se interrumpen.

Payload de un evento

{
  "id": "evt_01J3KZZAAA",
  "type": "factura.approved",
  "created_at": "2024-07-01T10:31:05",
  "data": {
    "id": "fact_01J3KZZXXYYY",
    "cdc": "01800695631001001000101001000007942024060111111111",
    "numero": "001-001-0000001",
    "status": "approved",
    "total": 550000
  }
}

Verificar la firma

Cada evento incluye el header X-DiFACT-Signature con una firma HMAC-SHA256 del body usando tu webhook secret. Verificala antes de procesar:

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');
  return `sha256=${expected}` === signature;
}