Webhooks de sinistro

A Sagas API envia notificações HTTP quando ocorrem mudanças relevantes no ciclo de vida de sinistros abertos via API (abertura, pagamento, conclusão etc.). Use webhooks para acompanhar o sinistro sem polling em GET /sinistros/{numero-sinistro}.

Para cadastrar assinaturas, autenticação e verificação de URL, consulte também a documentação geral de webhooks da Sagas API.

Pré-requisitos

• Canal com API de sinistros habilitada
• URL de destino que responda a POST com status 2xx (ex.: 204)
• Token OAuth2 válido para gerenciar assinaturas em /sagas/v1/webhooks

Configurar assinatura

Ao criar ou atualizar um webhook, informe em eventos-habilitados quais eventos aquela assinatura específica deve receber. Cada webhook tem sua própria lista — você escolhe um subconjunto dos eventos de sinistro disponíveis (veja Eventos de sinistro assináveis).

Um webhook só recebe entregas dos eventos que constam na sua assinatura. Outro webhook do mesmo canal pode assinar um conjunto diferente.

Exemplo com dois eventos:

curl --request POST \
  --url https://sagas.staging.180s.com.br/sagas/v1/webhooks \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "descricao": "Sinistros — abertura e conclusão",
    "ativo": true,
    "url": "https://seu-servidor.com/webhooks/sagas",
    "eventos-habilitados": [
      "sinistro-criado",
      "sinistro-finalizado"
    ]
  }'

Para alterar os eventos de uma assinatura existente, use PATCH /sagas/v1/webhooks/{id-webhook} com um novo array em eventos-habilitados. A resposta de GET /sagas/v1/webhooks reflete a lista configurada em cada registro.

Endpoints relacionados:

Formato da entrega

Todos os eventos seguem o mesmo envelope:

{
  "id-evento": "550e8400-e29b-41d4-a716-446655440000",
  "evento": "sinistro-criado",
  "criado-em": "2026-03-02T10:00:00Z",
  "versao": "1",
  "detalhes": {}
}

O objeto detalhes varia conforme o evento (veja abaixo).

Payload padrão

A maioria dos eventos de sinistro usa este formato em detalhes:

{
  "id-combo-produto": "3f2e6327-6fc4-491e-b2d1-7cd05c4a456b",
  "id-proposta": "ee60f961-8c56-45b1-be47-afa6b5092980",
  "id-venda": "442c176b-07a3-4a20-b41d-e780741fa5de",
  "numero-sinistro": "S123456789",
  "id-afiliacao": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Use numero-sinistro para consultar o sinistro em GET /sagas/v1/sinistros/{numero-sinistro}.

Payload de pagamento concluído

O evento sinistro-pagamento-concluido inclui dados para conciliação bancária:

{
  "id-combo-produto": "3f2e6327-6fc4-491e-b2d1-7cd05c4a456b",
  "id-proposta": "ee60f961-8c56-45b1-be47-afa6b5092980",
  "id-venda": "442c176b-07a3-4a20-b41d-e780741fa5de",
  "id-sinistro": "12cf4471-9f80-4622-b80b-5230b3e871d6",
  "id-transacao-financeira": "E20018183202408141147aseRqGSJGHM",
  "valor": 1000.00,
  "data-pagamento": "2026-03-15",
  "id-afiliacao": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Eventos de sinistro assináveis

Estes são os eventos de sinistro que podem aparecer em eventos-habilitados. Não é obrigatório assinar todos — inclua na sua assinatura apenas os relevantes ao seu fluxo.

Detalhes por evento

sinistro-criado — Disparado após a abertura bem-sucedida de um sinistro, seja via POST /vendas/{id-venda}/abrir-sinistro pelo canal ou em aberturas realizadas pela 180. Indica que o aviso foi registrado. Os detalhes completos — status, documentação pendente, valores etc. — podem ser obtidos em GET /sagas/v1/sinistros/{numero-sinistro} usando o numero-sinistro presente em detalhes.

sinistro-documentacao-em-analise — Disparado quando arquivos são recebidos após POST /sinistros/{numero-sinistro}/enviar-documento e upload na url-envio.

sinistro-documentacao-aprovada — Disparado quando a análise documental é concluída com aprovação. O sinistro segue para regulação ou solicitação de dados de pagamento.

sinistro-documentacao-negada — Disparado quando a seguradora solicita documentos adicionais ou substitutos. Consulte documentacao.documentos-pendentes em GET /sinistros/{numero-sinistro} para ver o que falta enviar.

sinistro-pendente-de-dados-de-pagamento — Disparado quando é necessário informar beneficiário e forma de pagamento. O canal pode complementar dados via fluxo whitelabel ou endpoints de pagamento, conforme contrato do produto.

sinistro-ajuste-de-reserva — Disparado quando o valor reservado para a indenização muda (ex.: após regulação ou atualização de saldo devedor). Consulte valor e valor-restante no sinistro.

sinistro-pagamento — Disparado quando um pagamento de indenização é registrado no sinistro. Diferente de sinistro-pagamento-concluido: indica a criação/aprovação do pagamento, não necessariamente a liquidação bancária.

sinistro-pagamento-concluido — Disparado quando o pagamento é efetivado. Use id-transacao-financeira para conciliação. Veja também a documentação de eventos de pagamento.

sinistro-finalizado — Disparado quando o sinistro é encerrado com sucesso (indenização concluída).

sinistro-negado — Disparado quando o sinistro é recusado. Consulte recusa em GET /sinistros/{numero-sinistro} para motivo e data.

sinistro-reaberto — Disparado quando um sinistro previamente finalizado ou recusado é reaberto para nova análise ou complementação.

Exemplo completo

Entrega de sinistro-criado:

{
  "id-evento": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "evento": "sinistro-criado",
  "criado-em": "2026-03-02T10:00:00Z",
  "versao": "1",
  "detalhes": {
    "id-combo-produto": "3f2e6327-6fc4-491e-b2d1-7cd05c4a456b",
    "id-proposta": "ee60f961-8c56-45b1-be47-afa6b5092980",
    "id-venda": "442c176b-07a3-4a20-b41d-e780741fa5de",
    "numero-sinistro": "S123456789"
  }
}

Boas práticas

• Assine apenas os eventos necessários ao seu fluxo — eventos-habilitados é por assinatura, não global ao canal
• Trate entregas como at-least-once: o mesmo id-evento pode ser recebido mais de uma vez — use-o para deduplicação
• Responda rapidamente com 2xx; processe a lógica de negócio de forma assíncrona se necessário
• Combine webhooks com Consultar sinistro para obter detalhes completos (documentacao, pagamentos, recusa etc.)

Referências

• Fluxo de sinistro — sequência de integração
• Status do sinistro — significado de cada status
• Webhooks — eventos (Sagas API) — envelope, autenticação e demais tipos de evento