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 (cancelamento confirmado). Os status transitórios (issuance_requested, cancellation_requested) e o encerramento natural de vigência (finished) não geram webhook — os transitórios são resultado das suas próprias chamadas, e o fim de vigência é conhecido desde a emissão pelo term.end_date.

Configuração de webhooks

Para receber webhooks é necessário ter uma URL de callback configurada. Veja Autenticação — Recebimento de webhooks.

Estrutura do webhook

Campo	Tipo	Descrição
webhook_type	string	Sempre insurance.policy.status_changed.
webhook_datetime	string	Data e hora do evento 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.
status	string	Novo status: issued ou canceled.
external_policy_number	string	Número da apólice na seguradora. Presente no evento de issued.
reason	string	Motivo do cancelamento. Presente no evento de canceled, quando informado.

Estrutura padrão do webhook

{
  "webhook_type": "insurance.policy.status_changed",
  "webhook_datetime": "2026-07-16T15:00:00Z",
  "data": {
    "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "status": "status",
    "external_policy_number": "APL-2026-000123",
    "reason": null
  }
}

Eventos por status

Apólice emitida

STATUS

issued

Enviado quando a seguradora confirma a emissão. A partir deste evento o external_policy_number está disponível e a cobertura está formalmente em vigor. Como cada apólice é emitida de forma independente, um pedido com N produtos gera N eventos deste tipo — possivelmente em momentos diferentes.

Webhook Body

{
  "webhook_type": "insurance.policy.status_changed",
  "webhook_datetime": "2026-07-16T15:00:00Z",
  "data": {
    "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "status": "issued",
    "external_policy_number": "APL-2026-000123",
    "reason": null
  }
}

---

Apólice cancelada

STATUS

canceled

Enviado quando a seguradora confirma o cancelamento — solicitado pelo cancelamento de apólice ou pelo cancelamento pós-emissão do pedido. A devolução de prêmio devida (integral dentro do direito de arrependimento, pró-rata depois) é calculada neste momento e executada pela QI Tech.

Webhook Body

{
  "webhook_type": "insurance.policy.status_changed",
  "webhook_datetime": "2026-08-02T09:30:00Z",
  "data": {
    "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "status": "canceled",
    "external_policy_number": "APL-2026-000123",
    "reason": "Cliente solicitou o cancelamento"
  }
}

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.