Webhooks Outbound

Receba notificações em tempo real sobre eventos da sua operação via HTTPS.

Como funciona

1. Você cadastra uma URL HTTPS + os eventos que quer receber
2. A API gera um HMAC secret (exibido apenas uma vez)
3. Quando o evento ocorre, enviamos um POST assinado com HMAC-SHA256
4. Se a entrega falhar, retentamos com backoff exponencial (ver Retry policy)

Eventos disponíveis

Lista canônica (corresponde ao enum webhook_event_type da API). A coluna Emitido indica se o evento é disparado pela API hoje: os eventos Sim são os detalhados em Eventos; os marcados Ainda não são reservados no enum (podem ser selecionados no cadastro do webhook, mas nenhuma entrega ocorre até a emissão ser ativada).

Proposta (proposal.*)

Uma proposta é uma operação ainda em avaliação, antes de se tornar uma operação efetiva.

Evento	Quando	Emitido
proposal.created	Proposta criada	Ainda não
proposal.simulated	Simulação registrada na proposta	Ainda não
proposal.approved	Proposta aprovada	Ainda não
proposal.denied	Proposta negada	Ainda não
proposal.expired	Proposta expirada	Ainda não

Operação (operation.*)

Evento	Quando	Emitido
operation.created	Operação criada	Sim
operation.pre_approved	Operação pré-aprovada	Ainda não
operation.approved	Aprovada (Backoffice ou automática)	Sim
operation.credit_analyzed	Análise de crédito concluída	Ainda não
operation.contract_sent	Contrato enviado para assinatura	Ainda não
operation.contract_signed	Contrato assinado por todos	Sim
operation.paid	Pagamento enviado ao cedente	Sim
operation.denied	Operação negada	Sim
operation.cancelled	Operação cancelada	Sim
operation.returning_capital_received	Capital de retorno recebido (parcial)	Ainda não
operation.fully_returned	Todo o capital retornado	Ainda não
operation.overdue	Operação com título(s) vencido(s)	Sim

Título (title.*)

Evento	Quando	Emitido
title.paid	Título individual liquidado	Sim
title.partially_paid	Pagamento parcial recebido	Sim
title.overdue	Título vencido sem pagamento	Ainda não

Estoque (stock.*)

Evento	Quando	Emitido
stock.item_registered	Recebível registrado no estoque	Sim
stock.item_consumed	Recebível consumido por uma operação	Ainda não

Payload e headers

Cada entrega é um POST com o corpo JSON do evento e os seguintes headers:

Header	Conteúdo
X-Zemo-Signature	HMAC-SHA256 do body
X-Zemo-Event-Type	Tipo do evento (ex.: operation.paid)
X-Zemo-Event-Id	UUID único do evento
X-Zemo-Timestamp	ISO 8601 UTC do envio

Exemplo de body:

{
  "event_type": "operation.paid",
  "event_id": "01970dc6-...",
  "occurred_at": "2026-06-01T15:30:00Z",
  "data": {
    "operation_id": "01970dc5-...",
    "display_number": "OP-A1B2C3D4-E5F6G7H8",
    "opr_liquid_value": "9183.33",
    "payment_sent_at": "2026-06-01T15:30:00Z"
  }
}

lifecycle_status nao vem em todo evento

Apenas operation.created e operation.approved trazem lifecycle_status no data. Nos demais eventos operation.* o estado alcancado esta implicito no event_type — se voce precisa do estado explicito, faca GET /v1/operations/{operation_id}. O payload exato de cada evento esta no Catalogo de Eventos.

Retry policy

• Aguardamos a resposta do seu endpoint por até 10 segundos (timeout de entrega).
• Uma resposta não-2xx ou um timeout conta como falha.
• Em falha, retentamos com backoff exponencial a partir de 1 min, dobrando a cada ciclo, até 7 tentativas no total (ou seja, a entrega inicial + 6 re-tentativas):

Tentativa	Ocorre após a falha anterior	Acumulado desde a 1ª
1	— (entrega inicial)	0
2	1 min	1 min
3	2 min	3 min
4	4 min	7 min
5	8 min	15 min
6	16 min	31 min
7 (última)	32 min	63 min

Esgotadas as 7 tentativas a entrega vai para failed. Existe ainda um prazo de desistência (give_up_at) de ~128 min contado da primeira falha: atingido o prazo, nenhuma re-tentativa é feita mesmo que sobrassem ciclos. O prazo não é uma tentativa — dimensione a janela de deduplicação por ele (~128 min), não pelos 63 min.

Esgotadas as tentativas, a entrega fica como failed e pode ser consultada em GET /v1/webhooks/{id}/deliveries.