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.

O token carrega os seguintes claims:

Claim	Descrição
timestamp	Data e hora UTC da geração da assinatura, no formato YYYY-MM-DDTHH:MM:SS.
method	Método HTTP da requisição. Sempre POST.
uri	URL completa configurada para o recebimento do webhook.
payload_md5	MD5 do corpo da requisição, em hexadecimal. Presente sempre que há corpo.

O corpo da requisição não é assinado diretamente. Para validar a integridade, decodifique o token e compare o payload_md5 com o MD5 do corpo recebido.

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

from jose import jwt

signature_key = "CHAVE UNICA CONFIGURADA"

signature_token = headers["SIGNATURE"]

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

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	-
Sandbox	-

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.