{
  "event": "document.created",
  "timestamp": "2024-04-14T10:00:00Z",
  "data": {
    "reference": "aaea7db4-647c-4d92-9f86-89e34a68e1aa",
    "beneficiary": {
      "reference": "616263a5-a677-4ad1-92ca-7e120adad8d4",
      "origin": "fiscal",
      "name": "Proveedor Ejemplo S.A.S",
      "identifier_type": "NIT",
      "identifier_number": "900123456",
      "is_deleted": false,
      "deleted_at": null,
      "contact_information": []
    },
    "document_number": "FC-2024-001",
    "type": "invoice",
    "issue_date": "2024-04-14T10:00:00Z",
    "expiration_date": "2024-04-30T10:00:00Z",
    "fiscal_reference": "e19d3e7867371a12fd53b67a56db087faa871c9797993d9bbf7806ae4e1466ea",
    "fiscal_metadata": {
      "final_notes": "Factura sujeta a retención en la fuente según artículo 383 del E.T."
    },
    "amount": 1190000,
    "amount_currency": "COP",
    "status": "pending",
    "payment_status": "pending",
    "file_path": "https://storage.payana.cloud/documents/FC-2024-001.pdf",
    "is_archived": false,
    "purchase_order": "OC-2024-001",
    "tags": [],
    "created_at": "2024-04-14T10:00:00Z",
    "updated_at": "2024-04-14T10:00:00Z"
  }
}

Webhooks

Document Created

Se envía cuando un nuevo documento es creado en Payana (por sincronización con la DIAN/SAT o carga manual). El payload incluye la referencia interna de Payana (reference), la referencia fiscal (fiscal_reference) y, cuando aplica, fiscal_metadata (hoy final_notes desde las notas UBL cbc:Note del XML).

Para marcar el documento como admitido en Payana (tag admitido, sin cambiar aprobación): POST /documents/{reference}/acknowledge.
Para aprobar el documento en el flujo de Payana: POST /documents/{reference}/approve (el path acepta UUID de Payana o CUFE / referencia fiscal).

El receptor del webhook debe responder con 200 para confirmar la recepción del evento.

WEBHOOK

document.created

{
  "event": "document.created",
  "timestamp": "2024-04-14T10:00:00Z",
  "data": {
    "reference": "aaea7db4-647c-4d92-9f86-89e34a68e1aa",
    "beneficiary": {
      "reference": "616263a5-a677-4ad1-92ca-7e120adad8d4",
      "origin": "fiscal",
      "name": "Proveedor Ejemplo S.A.S",
      "identifier_type": "NIT",
      "identifier_number": "900123456",
      "is_deleted": false,
      "deleted_at": null,
      "contact_information": []
    },
    "document_number": "FC-2024-001",
    "type": "invoice",
    "issue_date": "2024-04-14T10:00:00Z",
    "expiration_date": "2024-04-30T10:00:00Z",
    "fiscal_reference": "e19d3e7867371a12fd53b67a56db087faa871c9797993d9bbf7806ae4e1466ea",
    "fiscal_metadata": {
      "final_notes": "Factura sujeta a retención en la fuente según artículo 383 del E.T."
    },
    "amount": 1190000,
    "amount_currency": "COP",
    "status": "pending",
    "payment_status": "pending",
    "file_path": "https://storage.payana.cloud/documents/FC-2024-001.pdf",
    "is_archived": false,
    "purchase_order": "OC-2024-001",
    "tags": [],
    "created_at": "2024-04-14T10:00:00Z",
    "updated_at": "2024-04-14T10:00:00Z"
  }
}

Antes de procesar el evento, verifica la firma HMAC del request. Consulta Signature Verification en la introducción de la API.

Authorizations

api-key

string

header

required

API key provista por Payana.

Headers

X-Payana-Signature

string

required

X-Payana-Event

string

required

Allowed value: "document.created"

X-Payana-Timestamp

string<date-time>

required

Body

application/json

Webhook payload

event

string

required

Allowed value: "document.created"

timestamp

string<date-time>

required

data

object

required

Show child attributes

Response

200

Return 200 to acknowledge receipt

⌘I