Pular para o conteúdo principal

Webhook

Atualizações no status de fraude (Para Orders que sejam derivados para análise manual ou que sejam respondidos como Pendente) e para Sellers bloqueados, são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do suporte, configurar um endereço do endpoint por onde vamos notificar as atualizações e também uma signature_key que será utilizada para assinar a requisição.

No caso da atualização do status do pedido, o cliente pode também utilizar a técnica de polling. Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação de Order para proceder com o polling.

Atenção

Por questões de segurança, todas as requisições de Webhook serão somente realizadas em endpoints servidos por HTTPS.

Assinatura​

Exemplo de cálculo de assinatura em Python

    hmac_obj = hmac.new(signature_key.encode('utf-8'), (url + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()

Para garantir que a requisição recebida no endpoint do webhook parte dos nossos servidores, uma assinatura HMAC é enviada no Header Signature, de maneira semelhante ao processo de autenticação.

Após realizar o cálculo do valor esperado da assinatura do lado do servidor, é necessário comparar a assinatura calculada com a enviada. Caso as assinaturas sejam compatíveis, isso significa que a requisição partiu dos nossos servidores e que é confiável.

Webhook de Atualização de Order​

Request Body
    {
        "order_id": "123456",
        "fraud_status": "automatically_approved",
        "event_date": "2019-10-01T10:37:25-03:00"
    }

A requisição de atualização do status de análise de uma order possui o formato acima e notifica a mudança no status de fraude. O método utilizado é um PUT e o endereço do endpoint pode conter também o id do pedido, de acordo com a necessidade do cliente. É importante ressaltar que o corpo da requisição é enviado como texto codificado em UTF-8.

Exemplos de endpoints para atualização de pedido:

O campo event_date indica a data e hora em que a notificação foi criada e pode estar no passado caso envios de notificação anteriores tenham falhado.

Webhook de Atualização de Seller​

Exemplo de requisição de bloqueio de liquidação

Request Body
    {
        "document_number": "000.000.000-00",
        "settlement_status": "blocked",
        "event_date": "2019-10-01T10:37:25-03:00"
    }

Exemplo de requisição de bloqueio transacional

Request Body
    {
        "document_number": "000.000.000-00",
        "transactional_status": "blocked",
        "event_date": "2019-10-01T10:37:25-03:00"
    }

Caso o bloqueio ou desbloqueio de um seller seja necessário, o sistema da QI Tech realizará uma requisição com o formato acima. O método utilizado é um PUT realizado em um endpoint configurável e pode conter, a critério do cliente, o número do documento no endereço do endpoint.

Atenção

É a presença do campo settlement_status ou do campo transactional_status que determina o tipo de bloqueio ou desbloqueio que deve ser realizado no seller.

Exemplos de endpoints para atualização de seller:

Os seguintes status de liquidação podem ser notificados:

enumeradordescrição
blockedA liquidação do seller deve ser bloqueada
unblockedA liquidação do seller deve ser liberada

O campo event_date indica a data e hora em que a notificação foi criada e pode estar no passado caso envios de notificação anteriores tenham falhado.

Retentativas​

A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 7 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:

  • 10 segundos
  • 40 segundos
  • 160 segundos
  • 640 segundos
  • 2560 segundos
  • 10240 segundos
  • 40960 segundos