Eventos de webhook

Cuando le pasa algo a un documento, foliios envía un POST con el evento a tu endpoint de webhook. El cuerpo es JSON con id (estable: deduplica con él), type, created_at, environment, livemode y data. Cada petición lleva la firma HMAC-SHA256 en X-Webhook-Signature (t=<unix>,v1=<hex>, calculada sobre "<t>.<cuerpo>" con el secreto del endpoint) y las cabeceras X-Webhook-Id, X-Webhook-Event, X-Webhook-Attempt (0 en el primer intento) y Foliios-Environment (sandbox, test o live).

Los ejemplos usan valores fijos; en el sandbox, un evento de prueba tiene un documento doc_test_... que no existe.

`document.accepted`

La DIAN aceptó el documento (con o sin notificaciones). data.dian_messages trae las notificaciones, si las hay.

{
  "created_at": "2026-09-21T14:13:20.000000Z",
  "data": {
    "cufe": "5ab00609ab367da71db9cf10fe05a59d7c8b8e48c14cfcc9684cdf9bda3c73ee66da79533123b2e1bf0ec6a8fd5dc981",
    "dian_messages": [
      {
        "code": "RUT01",
        "message": "La validación del estado del RUT próximamente estará disponible.",
        "rejects": false
      }
    ],
    "document_id": "doc_test_01jd3xejemplo00000000000000",
    "document_version": 1,
    "failure_code": null,
    "number": "SBX0",
    "reason": null,
    "tenant_id": "cmp_ejemplo-sandbox",
    "transmission_deadline": null
  },
  "environment": "sandbox",
  "id": "01JD3XEJEMPLO00000000000000",
  "livemode": false,
  "type": "document.accepted"
}

`document.rejected`

La DIAN rechazó el documento. data.dian_messages trae las reglas que rechazan; corrige y reenvía con la API.

{
  "created_at": "2026-09-21T14:13:20.000000Z",
  "data": {
    "cufe": "5ab00609ab367da71db9cf10fe05a59d7c8b8e48c14cfcc9684cdf9bda3c73ee66da79533123b2e1bf0ec6a8fd5dc981",
    "dian_messages": [
      {
        "code": "FAD06",
        "message": "Valor del CUFE no está calculado correctamente",
        "rejects": true
      }
    ],
    "document_id": "doc_test_01jd3xejemplo00000000000000",
    "document_version": 1,
    "failure_code": null,
    "number": "SBX0",
    "reason": null,
    "tenant_id": "cmp_ejemplo-sandbox",
    "transmission_deadline": null
  },
  "environment": "sandbox",
  "id": "01JD3XEJEMPLO00000000000000",
  "livemode": false,
  "type": "document.rejected"
}

`document.failed`

El documento falló antes de llegar a un veredicto de la DIAN. data.failure_code es el código estable de la falla y data.reason la explica.

{
  "created_at": "2026-09-21T14:13:20.000000Z",
  "data": {
    "cufe": null,
    "dian_messages": [],
    "document_id": "doc_test_01jd3xejemplo00000000000000",
    "document_version": 1,
    "failure_code": "resolution_expired",
    "number": "SBX0",
    "reason": "resolution 18760000000000 does not cover document SBX0: the resolution expired (sandbox test event)",
    "tenant_id": "cmp_ejemplo-sandbox",
    "transmission_deadline": null
  },
  "environment": "sandbox",
  "id": "01JD3XEJEMPLO00000000000000",
  "livemode": false,
  "type": "document.failed"
}

`document.contingency`

La DIAN no estuvo disponible y el documento pasó a contingencia; foliios lo transmite cuando se restablezca. data.reason dice por qué.

{
  "created_at": "2026-09-21T14:13:20.000000Z",
  "data": {
    "cufe": "5ab00609ab367da71db9cf10fe05a59d7c8b8e48c14cfcc9684cdf9bda3c73ee66da79533123b2e1bf0ec6a8fd5dc981",
    "dian_messages": [],
    "document_id": "doc_test_01jd3xejemplo00000000000000",
    "document_version": 1,
    "failure_code": null,
    "number": "SBX0",
    "reason": "sandbox: la DIAN simulada no está disponible (evento de prueba)",
    "tenant_id": "cmp_ejemplo-sandbox",
    "transmission_deadline": null
  },
  "environment": "sandbox",
  "id": "01JD3XEJEMPLO00000000000000",
  "livemode": false,
  "type": "document.contingency"
}

`document.contingency_deadline_approaching`

Un documento sigue en contingencia y se acerca su plazo de 48 horas para transmitirse. data.transmission_deadline es el plazo, en hora de Colombia.

{
  "created_at": "2026-09-21T14:13:20.000000Z",
  "data": {
    "cufe": "5ab00609ab367da71db9cf10fe05a59d7c8b8e48c14cfcc9684cdf9bda3c73ee66da79533123b2e1bf0ec6a8fd5dc981",
    "dian_messages": [],
    "document_id": "doc_test_01jd3xejemplo00000000000000",
    "document_version": 1,
    "failure_code": null,
    "number": "SBX0",
    "reason": "sandbox: la DIAN simulada no está disponible (evento de prueba)",
    "tenant_id": "cmp_ejemplo-sandbox",
    "transmission_deadline": "2026-09-21T15:13:20"
  },
  "environment": "sandbox",
  "id": "01JD3XEJEMPLO00000000000000",
  "livemode": false,
  "type": "document.contingency_deadline_approaching"
}

`document.delivered`

El correo con el documento llegó al servicio de correo para el comprador. data.delivery trae el estado del envío.

{
  "created_at": "2026-09-21T14:13:20.000000Z",
  "data": {
    "cufe": "5ab00609ab367da71db9cf10fe05a59d7c8b8e48c14cfcc9684cdf9bda3c73ee66da79533123b2e1bf0ec6a8fd5dc981",
    "delivery": {
      "attempts": 1,
      "failure_code": null,
      "message_id": "msg_01jd3xejemplo00000000000000",
      "recipients": [
        "comprador@sandbox.foliios.example"
      ],
      "stage": "validated",
      "status": "sent",
      "trigger": "accepted"
    },
    "dian_messages": [],
    "document_id": "doc_test_01jd3xejemplo00000000000000",
    "document_version": 1,
    "failure_code": null,
    "number": "SBX0",
    "reason": null,
    "tenant_id": "cmp_ejemplo-sandbox",
    "transmission_deadline": null
  },
  "environment": "sandbox",
  "id": "01JD3XEJEMPLO00000000000000",
  "livemode": false,
  "type": "document.delivered"
}

`document.delivery_failed`

El envío por correo falló de forma definitiva y necesita a una persona. data.delivery.failure_code es el código estable.

{
  "created_at": "2026-09-21T14:13:20.000000Z",
  "data": {
    "cufe": "5ab00609ab367da71db9cf10fe05a59d7c8b8e48c14cfcc9684cdf9bda3c73ee66da79533123b2e1bf0ec6a8fd5dc981",
    "delivery": {
      "attempts": 1,
      "failure_code": "mailer_rejected",
      "message_id": null,
      "recipients": [
        "comprador@sandbox.foliios.example"
      ],
      "stage": "validated",
      "status": "failed",
      "trigger": "accepted"
    },
    "dian_messages": [],
    "document_id": "doc_test_01jd3xejemplo00000000000000",
    "document_version": 1,
    "failure_code": null,
    "number": "SBX0",
    "reason": "El servicio de correo rechazó el mensaje de forma permanente. Revise el correo del comprador y reenvíe.",
    "tenant_id": "cmp_ejemplo-sandbox",
    "transmission_deadline": null
  },
  "environment": "sandbox",
  "id": "01JD3XEJEMPLO00000000000000",
  "livemode": false,
  "type": "document.delivery_failed"
}

`document.delivery_not_applicable`

El documento no tiene correo del comprador: debe llegarle por otro medio (la representación gráfica impresa).

{
  "created_at": "2026-09-21T14:13:20.000000Z",
  "data": {
    "cufe": "5ab00609ab367da71db9cf10fe05a59d7c8b8e48c14cfcc9684cdf9bda3c73ee66da79533123b2e1bf0ec6a8fd5dc981",
    "delivery": {
      "attempts": 1,
      "failure_code": null,
      "message_id": null,
      "recipients": [],
      "stage": "validated",
      "status": "not_applicable",
      "trigger": "accepted"
    },
    "dian_messages": [],
    "document_id": "doc_test_01jd3xejemplo00000000000000",
    "document_version": 1,
    "failure_code": null,
    "number": "SBX0",
    "reason": "the document has no e-mail of the buyer: deliver the graphic representation by another means (annex 1.9, 9.3)",
    "tenant_id": "cmp_ejemplo-sandbox",
    "transmission_deadline": null
  },
  "environment": "sandbox",
  "id": "01JD3XEJEMPLO00000000000000",
  "livemode": false,
  "type": "document.delivery_not_applicable"
}