Configurando webhooks
A QI Tech notifica as mudanças de status dos seus pedidos e apólices por POST na URL de webhook configurada para a sua integração. Cada webhook é assinado pela QI Tech e deve ser validado antes de ser processada.
Eventos disponíveis
webhook_type | Quando é enviado | Detalhes |
|---|---|---|
insurance.order.status_changed | A cada mudança de status do pedido: criado, recusado, emitido, expirado ou cancelado antes da emissão. | Webhooks do pedido |
insurance.policy.status_changed | Quando a apólice é emitida pela seguradora e quando é cancelada. | Webhooks da apólice |
Como configurar
No Insurance-as-a-Service a configuração dos webhooks não está disponível pelo portal QI Tech. Ela é feita pelo time de Integração da QI Tech.
Envie para api@qitech.com.br:
- A URL de webhook, por ambiente (sandbox e produção). A URL deve ser HTTPS, aceitar
POST, ter no máximo 200 caracteres e não conter fragmento (#...). - Os headers que você precisa que a QI Tech envie em cada webhook, se houver — por exemplo um header de autenticação do seu lado.
Uma mesma URL recebe todos os eventos. Se você precisar de uma URL diferente para cada tipo de evento, informe no pedido.
Em retorno, você recebe a chave pública da QI Tech (PEM), exclusiva da sua integração, que valida a assinatura de cada webhook.
Avise-nos com antecedência quando a URL mudar: enquanto a alteração não for registrada, os webhooks continuam sendo enviados para o endereço anterior.
Formato dos webhooks
Todo webhook do Insurance-as-a-Service tem a mesma estrutura:
| Campo | Tipo | Descrição |
|---|---|---|
webhook_type | string | Tipo do evento. Veja a tabela de eventos disponíveis. |
status | string | Novo status do pedido ou da apólice. |
key | string | Chave do recurso notificado: o order_key nos eventos de pedido, o policy_key nos de apólice. |
event_datetime | string | Data e hora do evento, em UTC, no formato ISO 8601 com precisão de segundos. |
data | object | Dados do evento. Os atributos de cada tipo estão nas páginas de detalhe. |
{
"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
}
}
Headers
| Header | Descrição |
|---|---|
AUTHORIZATION | JWT ES512 com a assinatura da QI Tech. Se você configurou um header próprio chamado AUTHORIZATION, a assinatura chega em QI-AUTHORIZATION. |
API-CLIENT-KEY | Chave que identifica a sua integração. |
webhook_key | Identificador único do webhook. Um webhook reenviado mantém o mesmo valor. |
webhook-type | O mesmo webhook_type do corpo. |
Content-Type | application/json. |
Os nomes de header não diferenciam maiúsculas de minúsculas: dependendo do seu servidor, eles podem chegar como Authorization ou Api-Client-Key.
Como responder
Responda com o status 200, 201, 202 ou 204 em até 10 segundos. Qualquer outro status, ou a falta de resposta nesse prazo, conta como falha de entrega.
A entrega é do tipo best-effort: um webhook que falhou não é reenviado automaticamente. Não dependa exclusivamente dos webhooks — o estado atual de um pedido ou de uma apólice pode sempre ser consultado em GET /v1/insurance/orders/{order_key} e GET /v1/insurance/policies/{policy_key}.
Ordem e duplicidade
Os webhooks não chegam necessariamente na ordem em que os eventos aconteceram. Para saber qual é a mais recente, use data.sequence: dentro de um mesmo pedido ou de uma mesma apólice, um valor maior é sempre um evento posterior. A sequência não é contínua — não conte com valores consecutivos.
Para descartar um webhook já processado, use o header webhook_key.
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.