Dynamic Fields – Webhook v1.1.0

Owned by Guilherme de Assis Mello
Last updated: ago. 29, 2024 by Secretariado Open Insurance
3 min read

  • damage-and-person

  • capitalization-title

Na API de campos dinâmicos, a seguradora envia uma notificação a SPOC informando que ocorreu uma alteração nos campos customizáveis utilizados no processo de cotação, logo, a iniciadora deverá consultar a API de campos dinâmicos da seguradora para manter os campos atualizados em sua base.

Obrigatoriedade de notificação

A deliberação sobre a obrigatoriedade de notificação da alteração dos campos dinâmicos pelas seguradoras se teve através de discussões realizadas no GT de Infraestrutura e Tecnologia, pelo fato de que as seguradoras precisam comunicar todas as SPOCs do ecossistema, para evitar acesso excessivo via polling. É necessário que a SPOC confirme a atualização realizada para a seguradora, via Webhook

Já a SPOC por sua vez, ao entrar no ecossistema, deverá consumir os campos dinâmicos de todas as seguradoras que o possuam, e confirmar o consumo via Webhook.

  • Seguradora: Notificar todas as SPOCs, quando houver alteração em seus campos customizáveis, ou entrar pela primeira vez no ecossistema (Obrigatório)

  • SPOC: Consumir os campos customizáveis de todas as seguradoras ao entrar pela primeira vez no ecossistema, ou quando for recebida notificação via webhook (Obrigatório)

Para mais detalhes vide diagrama de sequência de manutenção dos campos dinâmicos.

OBS: A implementação da API de Dynamic Fields é de caráter opcional, visto que somente aquelas instituições que necessitam de informações adicionais do cliente, no momento da cotação, devem realizar a implementação dessa API.

Conteúdo do Payload/URL

O payload será composto pela informação do timestamp do momento da alteração dos campos dinâmicos:

image-20240409-203746.png

URL

As URLs do ecossistema são formadas com a configuração abaixo:
<host> / <string> / <api> / <versão> / <recurso>

As seguradoras precisam construir a URI de notificação da seguinte forma:

 

image-20240409-204548.png

 

Quando habilitar a funcionalidade de Webhook para as API de Dynamic Fields, a iniciadora deverá estar apta a receber notificações nos seguintes endereços:

  • https://insurSpocExemplo.com/open-insurance/webhook/[Versão do Webhook]/dynamic-fields/{AsId}/v1/damage-and-person

  • https://insurSpocExemplo.com/open-insurance/webhook/[Versão do Webhook]/dynamic-fields/{AsId}/v1/capitalization-title

Segurança

  • Todos os endpoints do Webhook utilizam-se de mTLS para autenticação, não possuem scopes e permissions específicos de segurança. Toda a segurança é feita via certificado(mTLS – BRCAC).

  • Não será necessário a assinatura do webhook, pois não vai haver dados sensíveis no conteúdo do Payload.

Orientação em caso de falha

Em caso de falha de notificação a SPOC deve:

  • A iniciadora, ao perceber que não está recebendo as notificações oriundas da seguradora, poderá utilizar os endpoints de consulta para obter informações as alterações nos campos dinâmicos.

  • Endpoints para consulta de campos dinâmicos:

GET/damage-and-person

GET/capitalization-title

Orientações para as receptoras

  • Orientações para as receptoras:

    • A receptora de conta fará no máximo 3 tentativas de notificação para a iniciadora:

    • A segunda e a terceira tentativas só ocorrerão em caso de falha;

    • A primeira tentativa de notificação do evento, pela receptora, deverá ocorrer em até 1,5 segundo após o evento;

    • A segunda tentativa deverá ocorrer 10 segundos após a falha da primeira tentativa;

    • A terceira tentativa deverá ocorrer 60 segundos após a falha da segunda tentativa;