Webhook para notificar créditos baixos

Para notificar uma URL de sua escolha quando os seus créditos estiverem baixos, você deve entrar no seu Perfil no site da api do QualP e cadastrar um webhook.

#Configurando webhook

Para configurar o webhook são necessarios os seguintes parâmetros:

• URL de notificação: É a URL que será notificada quando os créditos atingirem o valor especificado.
• Secret: o webhook será criptografado com o secret informado criando uma assinatura que será utilizada posteriormente para validar esse webhook.
• Créditos: A notificação será enviada quando os créditos do usuário atingirem esse valor especificado.

#Estrutura do webhook

Após esse webhook ser cadastrado e os créditos do usuário atingirem o valor informado, a URL especificada receberá uma requisição do tipo POST. O header da requisição terá um parâmetro chamado signature contendo uma hash referente ao conteúdo da request encriptografada com o secret. O corpo da requisição será uma versão codificada em json. Como podemos ver no exemplo abaixo:

#header da requisição

"signature" : "494fe7146e4cd162c9358a1d1c0cfabf562275f1c3d6146a05bcf3c4c59c360e"

#Corpo da requisição

{
    "user" : {
      "id": 123456,
      "username": "joao",
      "email": "[email protected]",
      "cpf_cnpj": "12345678910",
      "access_token": "sahfjkashdfasjhdfalkshfdaskjhf",
      "company_name": null,
      "phone": null,
      "original_id": null,
      "created_at": "2020-08-27T18:10:01.000000Z",
      "updated_at": "2020-08-27T18:10:01.000000Z",
      "is_active": 1
    },
    "credits" : 0,
    "webhook" : {
      "type" : "low-credits-webhook"
    }
}

#Recebendo o webhook

Receber o webhook no site informado é bem simples, basta apenas tratar o corpo da request que está codificado em json. Para verificar a autenticidade de um webhook é necessário utilizar o parâmetro signature que esta setado no header da requisição. Veja alguns exemplos abaixo:

#Exemplo Laravel

    //A variável $secret refere-se ao secret cadastrado no webhook
    $computedSignature = hash_hmac('sha256', $request->getContent(), $secret);
    
    //O $computedSignature deve conter o mesmo hash se comparado com o parâmetro signature setado no header, caso o contrário esse webhook é inválido.
    if ($computedSignature === $request->header('signature')) {
        //webhook válido
    }else{
        //webhook inválido
    }

#Exemplo Node

const http = require("http");
let crypto = require('crypto');

const server = http.createServer((req, res) => {
    if (req.method == 'POST') {
        let jsonString = '';
    
        req.on('data', function (data) {
            jsonString += data;
        });
    
        req.on('end', function () {
            //A variável secret refere-se ao secret cadastrado no webhook
            let computedSignature = crypto.createHmac('sha256', 'secret').update(jsonString).digest('hex');
            //O computedSignature deve conter o mesmo hash se comparado com o parâmetro signature setado no header, caso o contrário esse webhook é inválido.
            if (computedSignature === req.headers['signature']) {
                //webhook válido
            }else{
                //webhook inválido
            }
        });
    }
})