Recebimento de Webhooks

A assinatura dos Webhooks utiliza-se de uma estratégia de criptografia com chaves simétricas, ou seja, tanto a QI CTVM quanto o Parceiro integrador compartilham de uma mesma chave. Ao realizarmos uma configuração de Webhooks, iremos gerar uma Signature Key e disponibiliza-lá. Toda requisição originada no sistema da QI, irá carregar um header SIGNATURE que será um JWT assinado com essa chave. O encoding é realizado com o algoritmo HS256.

Abaixo temos um exemplo em python de como realizar o decoding da assinatura:

from jose import jwt

signature_key = "CHAVE UNICA DISPONIBILIZADA PELO TIME QI"

signature_token = headers["SIGNATURE"]

decoded_token = jwt.decode(signature_token, key=signature_key, algorithms=["HS256"])
print(decoded_token)

O que a assinatura carrega

O JWT decodificado traz quatro campos:

Campo	Descrição
timestamp	Data e hora da assinatura, em UTC, no formato AAAA-MM-DDTHH:MM:SS.
method	Método HTTP da requisição — sempre POST.
uri	A URL de destino configurada para o seu webhook.
payload_md5	Hash MD5 do corpo da requisição.

Use o payload_md5 para validar integridade

Calcular o MD5 do corpo recebido e comparar com payload_md5 confirma que o payload não foi alterado em trânsito. Como o hash é calculado sobre o corpo serializado, compare os bytes recebidos — não o resultado de um re-encode do JSON depois de parsear.

Além do SIGNATURE, as requisições levam o header AGENT-KEY, com o identificador do agente (classe de fundo, investidor ou gestor) a que a notificação se refere. Ele é útil para rotear a notificação quando a sua integração atende mais de um fundo pela mesma URL.

Tentativas de entrega

Consideramos a entrega bem-sucedida quando a sua aplicação responde com um status de sucesso. Em caso de falha — resposta de erro ou erro de rede — a notificação volta para a fila e é retentada.

São feitas até 5 tentativas por notificação. Esgotadas as tentativas, ela é marcada como falha e não é mais retentada automaticamente.

Notificação que não chegou

Uma notificação que falhou nas 5 tentativas pode ser reenviada pela QI CTVM — entre em contato com o time de integração informando o período e o tipo de evento. O reenvio não é uma operação disponível na sua integração.

Trate o recebimento como idempotente

Uma tentativa pode ter chegado à sua aplicação e a resposta ter se perdido, o que faz a notificação ser retentada. Sua aplicação precisa tolerar receber a mesma notificação mais de uma vez — use as chaves do payload para reconhecer o que já foi processado.

Validação de origem

Sugerimos que, além de comparar a assinatura, o parceiro integrador valide o nosso IP, dado que todas as nossas requisições são originadas de um mesmo IP, conforme o ambiente:

Ambiente	IP
Produção	54.205.166.229
Sandbox	52.72.221.4

Atenção!

Os webhooks da QI CTVM não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.