Pular para o conteúdo principal

Eventos de Webhook

Todo evento chega no MESMO envelope — event_type, event_id, occurred_at e data — e os quatro campos estao SEMPRE presentes, inclusive nas re-entregas. O event_id e a chave de deduplicacao: a entrega e at-least-once, entao o mesmo event_id pode chegar mais de uma vez e o consumidor precisa ser idempotente. Ele tambem viaja no header X-Zemo-Event-Id. O schema completo do envelope e de cada data esta na secao webhooks do openapi.json.

Os exemplos abaixo detalham o data de cada evento EMITIDO hoje.

Dois nomes para o mesmo valor

Os valores monetarios do data viajam com o nome canonico e o deprecado lado a lado, sempre com o mesmo numero — opr_net_present_liquid_value acompanha opr_liquid_value, como nos exemplos abaixo. Leia o canonico; o deprecado continua sendo enviado em toda a serie 1.x — a politica esta declarada em Versionamento. Na 2.0 os eventos NOVOS passam a ser emitidos so com os nomes canonicos (eventos antigos que forem reentregues preservam o shape com que foram gravados). O de-para campo a campo esta em Valores do Recebivel.

Na janela de re-tentativa (ate ~128 min por evento) pode chegar um evento GERADO antes desta mudanca: o conteudo entregue e o que foi registrado na emissao, e eventos antigos foram registrados so com o nome deprecado — o espelho nao e aplicado retroativamente. Por isso o nome canonico nao e declarado obrigatorio no schema: trate a ausencia dele caindo no nome deprecado.

operation.created​

Disparado quando uma operacao e criada (e, quando aplicavel, aguarda aprovacao do Backoffice).

{
  "event_type": "operation.created",
  "event_id": "793acf45-ac11-4629-acab-5efdd7e84541",
  "occurred_at": "2026-06-01T12:00:00Z",
  "data": {
    "operation_id": "...",
    "display_number": "OP-A1B2C3D4-E5F6G7H8",
    "opr_liquid_value": "9183.33",
    "opr_net_present_liquid_value": "9183.33",
    "lifecycle_status": "WAITING_APPROVAL"
  }
}

operation.approved​

Disparado quando a operacao e aprovada (pelo Backoffice ou automaticamente).

{
  "event_type": "operation.approved",
  "event_id": "33bff6c8-d396-4eaa-b1fa-6c1b617d1db2",
  "occurred_at": "2026-06-01T15:00:00Z",
  "data": {
    "operation_id": "...",
    "display_number": "OP-A1B2C3D4-E5F6G7H8",
    "lifecycle_status": "APPROVED_DIRECT",
    "approved_at": "2026-06-01T15:00:00Z"
  }
}

operation.contract_signed​

Todos os signatarios assinaram o contrato via ZapSign.

{
  "event_type": "operation.contract_signed",
  "event_id": "2c266515-3d55-4278-9f53-1a4649823d78",
  "occurred_at": "2026-06-01T14:00:00Z",
  "data": {
    "operation_id": "...",
    "contract_id": "...",
    "signed_at": "2026-06-01T14:00:00Z"
  }
}

operation.paid​

Pagamento PIX enviado ao cedente.

{
  "event_type": "operation.paid",
  "event_id": "c7f22723-47fc-4c5e-ba06-5b732f9ede9b",
  "occurred_at": "2026-06-01T15:30:00Z",
  "data": {
    "operation_id": "...",
    "display_number": "OP-A1B2C3D4-E5F6G7H8",
    "opr_liquid_value": "9183.33",
    "opr_net_present_liquid_value": "9183.33",
    "payment_sent_at": "2026-06-01T15:30:00Z"
  }
}

operation.denied​

Operacao negada pelo Backoffice.

{
  "event_type": "operation.denied",
  "event_id": "de5e35da-d35b-4753-a1e9-0aae84374f21",
  "occurred_at": "2026-06-01T16:00:00Z",
  "data": {
    "operation_id": "...",
    "reason": "Motivo da negacao"
  }
}

operation.cancelled​

Operacao cancelada pelo originador.

{
  "event_type": "operation.cancelled",
  "event_id": "52db7750-9299-4c91-91ec-24d27510ada7",
  "occurred_at": "2026-06-01T12:00:00Z",
  "data": {
    "operation_id": "...",
    "cancelled_at": "2026-06-01T12:00:00Z"
  }
}

title.paid​

Titulo individual totalmente liquidado.

{
  "event_type": "title.paid",
  "event_id": "357f59e8-5812-47d9-b8c1-2ed2b8277083",
  "occurred_at": "2026-08-15T10:00:00Z",
  "data": {
    "title_id": "...",
    "operation_id": "...",
    "face_value": "10000.00",
    "total_returned_value": "10000.00",
    "fully_returned_at": "2026-08-15T10:00:00Z"
  }
}

title.partially_paid​

Pagamento parcial recebido em um titulo.

{
  "event_type": "title.partially_paid",
  "event_id": "08d17fdc-adb5-4067-87bf-1c14b0f43fa0",
  "occurred_at": "2026-08-10T10:00:00Z",
  "data": {
    "title_id": "...",
    "operation_id": "...",
    "payment_amount_brl": "5000.00",
    "outstanding_brl": "5000.00"
  }
}

operation.overdue​

Um ou mais titulos da operacao venceram sem pagamento total.

{
  "event_type": "operation.overdue",
  "event_id": "697abe45-189a-4314-bd1f-4cbac2ff194c",
  "occurred_at": "2026-08-16T03:00:00Z",
  "data": {
    "operation_id": "...",
    "overdue_titles_count": 2,
    "total_outstanding_brl": "5000.00"
  }
}

stock.item_registered​

Recebivel registrado no estoque.

{
  "event_type": "stock.item_registered",
  "event_id": "81cb6393-f2ea-48a9-82f2-e78c9f3b9015",
  "occurred_at": "2026-06-01T09:00:00Z",
  "data": {
    "stock_item_id": "...",
    "external_id": "NF-2026-001",
    "face_value": "10000.00"
  }
}