Webhooks do pedido

A cada mudança de status do pedido, a QI Tech envia um webhook do tipo insurance.order.status_changed para a sua URL de webhook. O evento identifica o pedido pelo order_key e carrega o novo status.

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.order.status_changed.
status	string	Novo status do pedido.
key	string	Chave do pedido (order_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
order_key	string	Chave do pedido.
requester_key	string	Chave da sua integração como distribuidor.
status	string	Novo status do pedido — o mesmo do campo status externo.
customer_document_number	string	Documento do segurado.
reason	array / string / null	Motivo da mudança: a lista de decline_reasons em rejected, o motivo informado em cancelled e null nos demais. A chave está sempre presente.
product_count	integer	Quantidade de produtos do pedido. No evento de emitted, é o número de apólices que serão emitidas.
sequence	integer	Ordem do evento dentro do pedido: o evento de criação é 1 e cada mudança seguinte tem um valor maior. Use-o para ordenar webhooks que chegarem fora de ordem.
schema_version	integer	Versão da estrutura de data. Atualmente 1.

Estrutura padrão do webhook

{
  "status": "awaiting_payment",
  "webhook_type": "insurance.order.status_changed",
  "key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "event_datetime": "2026-10-05T15:56:49Z",
  "data": {
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "requester_key": "3f1c9a2e-4b7d-4e0a-9c55-2d8e7f6a1b30",
    "status": "awaiting_payment",
    "customer_document_number": "96969879003",
    "reason": null,
    "product_count": 1,
    "sequence": 1,
    "schema_version": 1
  }
}

Eventos por status

Pedido criado

STATUS

awaiting_payment

Enviado quando a criação do pedido é concluída com sucesso. O pedido aguarda o pagamento da primeira parcela pelo payment_artifact Pix retornado na criação. A estrutura é a do exemplo acima.

---

Pedido recusado

STATUS

rejected

Enviado quando o pedido nasce recusado na criação porque a precificação recusou ao menos uma linha. O campo reason traz a lista de decline_reasons, uma entrada por falha, com os mesmos códigos da cotação.

Webhook Body

{
  "status": "rejected",
  "webhook_type": "insurance.order.status_changed",
  "key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "event_datetime": "2026-10-05T16:06:22Z",
  "data": {
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "requester_key": "3f1c9a2e-4b7d-4e0a-9c55-2d8e7f6a1b30",
    "status": "rejected",
    "customer_document_number": "96969879003",
    "reason": [
      {
        "product_key": "8a6f2c1d-3b4e-4f5a-9b8c-7d6e5f4a3b2c",
        "code": "OUT_OF_OPTION_SPACE",
        "detail": "1f2e3d4c-5b6a-4789-8a7b-6c5d4e3f2a1b: insured_amount: 60000 is outside the offered range 0-50000.0"
      }
    ],
    "product_count": 1,
    "sequence": 1,
    "schema_version": 1
  }
}

---

Pedido emitido

STATUS

emitted

Enviado quando o pagamento da primeira parcela é confirmado e a emissão das apólices é disparada. O campo product_count indica quantas apólices serão criadas — o evento não carrega as chaves das apólices, porque elas são criadas de forma assíncrona logo em seguida. No sandbox, o pagamento pode ser simulado. Descubra as apólices com GET /v1/insurance/policies?order_key= ou aguarde os webhooks de apólice.

Webhook Body

{
  "status": "emitted",
  "webhook_type": "insurance.order.status_changed",
  "key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "event_datetime": "2026-10-05T15:59:34Z",
  "data": {
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "requester_key": "3f1c9a2e-4b7d-4e0a-9c55-2d8e7f6a1b30",
    "status": "emitted",
    "customer_document_number": "96969879003",
    "reason": null,
    "product_count": 1,
    "sequence": 2,
    "schema_version": 1
  }
}

---

Pedido expirado

STATUS

expired

Enviado quando o prazo de pagamento (expires_at) vence sem confirmação. O vencimento é verificado a cada 15 minutos, então o evento pode chegar até 15 minutos depois do prazo. A expiração nunca desfaz um pagamento válido: se o pagamento for confirmado antes do processamento da expiração, o pedido é emitido normalmente e este evento não ocorre.

Webhook Body

{
  "status": "expired",
  "webhook_type": "insurance.order.status_changed",
  "key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "event_datetime": "2026-10-13T00:00:12Z",
  "data": {
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "requester_key": "3f1c9a2e-4b7d-4e0a-9c55-2d8e7f6a1b30",
    "status": "expired",
    "customer_document_number": "96969879003",
    "reason": null,
    "product_count": 1,
    "sequence": 2,
    "schema_version": 1
  }
}

---

Pedido cancelado

STATUS

cancelled

Enviado quando o cancelamento antes da emissão é concluído. O campo reason traz o motivo informado no cancelamento, ou null se nenhum foi informado.

O cancelamento depois da emissão não gera este evento: o pedido permanece emitted e cada apólice é cancelada, o que é notificado pelos webhooks de apólice.

Webhook Body

{
  "status": "cancelled",
  "webhook_type": "insurance.order.status_changed",
  "key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "event_datetime": "2026-10-05T15:59:20Z",
  "data": {
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "requester_key": "3f1c9a2e-4b7d-4e0a-9c55-2d8e7f6a1b30",
    "status": "cancelled",
    "customer_document_number": "96969879003",
    "reason": "Cliente desistiu da contratação",
    "product_count": 1,
    "sequence": 2,
    "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.