Webhooks da apólice

Os marcos do ciclo de vida da apólice são notificados por webhooks do tipo insurance.policy.status_changed. Dois status geram evento: issued (emissão confirmada pela seguradora) e canceled (apólice cancelada). O encerramento natural de vigência (finished) não gera webhook — ele é conhecido desde a emissão pelo term.end_date.

Cada apólice é notificada de forma independente: um pedido com N produtos gera N apólices e N eventos de cada tipo, possivelmente em momentos diferentes.

Configuração e validação

Para receber webhooks é necessário ter uma URL de webhook configurada, e cada webhook deve ter a assinatura validada. Veja Configurando webhooks e Validação de webhooks.

Estrutura do webhook

Campo	Tipo	Descrição
webhook_type	string	Sempre insurance.policy.status_changed.
status	string	Novo status da apólice: issued ou canceled.
key	string	Chave da apólice (policy_key).
event_datetime	string	Data e hora do evento, em UTC, no formato ISO 8601.
data	object	Dados do evento. Veja tabela abaixo.

Atributos de data

Campo	Tipo	Descrição
policy_key	string	Chave da apólice.
order_key	string	Chave do pedido que originou a apólice — a correlação com a sua venda.
requester_key	string	Chave da sua integração como distribuidor.
status	string	Novo status da apólice — o mesmo do campo status externo.
external_policy_number	string	Número da apólice na seguradora.
reason	string / null	Motivo do cancelamento no evento de canceled; null no de issued.
sequence	integer	Ordem do evento dentro da apólice: um valor maior é sempre um evento posterior. A sequência não é contínua — o primeiro webhook de uma apólice pode chegar com um valor maior que 1.
schema_version	integer	Versão da estrutura de data. Atualmente 1.

Atenção

O status de cancelamento da apólice é canceled, com um l. O do pedido é cancelled, com dois. Trate os dois valores separadamente.

Eventos por status

Apólice emitida

STATUS

issued

Enviado quando a seguradora confirma a emissão. A partir deste evento a cobertura está formalmente registrada na seguradora.

Webhook Body

{
  "status": "issued",
  "webhook_type": "insurance.policy.status_changed",
  "key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
  "event_datetime": "2026-10-05T20:41:02Z",
  "data": {
    "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "requester_key": "3f1c9a2e-4b7d-4e0a-9c55-2d8e7f6a1b30",
    "status": "issued",
    "external_policy_number": "QIS000000000123",
    "reason": null,
    "sequence": 1,
    "schema_version": 1
  }
}

---

Apólice cancelada

STATUS

canceled

Enviado quando a apólice é cancelada — pelo cancelamento da apólice ou do pedido depois da emissão, no momento do cancelamento, ou pela seguradora. O campo reason traz o motivo informado no cancelamento, ou requester_requested se nenhum foi informado; num cancelamento feito pela seguradora, ele vem como provider_initiated.

Webhook Body

{
  "status": "canceled",
  "webhook_type": "insurance.policy.status_changed",
  "key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
  "event_datetime": "2026-10-05T21:18:33Z",
  "data": {
    "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "requester_key": "3f1c9a2e-4b7d-4e0a-9c55-2d8e7f6a1b30",
    "status": "canceled",
    "external_policy_number": "QIS000000000123",
    "reason": "Cliente solicitou o cancelamento",
    "sequence": 3,
    "schema_version": 1
  }
}

Atenção!

Os webhooks da QI Tech não devem ser mapeados de forma estrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.