As integrações webook existem em diversas aplicações. Elas nada mais são que mensageiros que alertam o app, sistema ou ferramenta de que algo está acontecendo. Assim como as APIs, os webhooks permitem que diferentes sistemas se comuniquem entre si e compartilhem informações.
Por conta dessa característica, muitas pessoas costumam achar que APIs e webhooks têm o mesmo significado, mas neste artigo esclarecemos para você as diferenças entre eles. Além disso, explicamos o que são webhooks com mais detalhes e como criar um. Boa leitura!
O que é o webhook?
Um webhook é um recurso que possibilita que um sistema, ferramenta ou aplicativo se comunique com outro sistema, ferramenta ou aplicativo e troque dados entre si. Essa troca ocorre em tempo real e sempre que um evento qualificado acontece.
Por exemplo, é possível automatizar sistemas de alerta nos quais o evento acionador é a loja virtual receber uma confirmação de pagamento sempre que um cliente concluir uma compra.
O termo surgiu em 2007 e foi criado por Jeff Lindsay, a partir de uma palavra usual na programação de computador: hook, que significa “gancho” em português.
Graças a essa tecnologia é que um usuário recebe notificações quando algo novo se passa em seu sistema. Por essa razão, webhooks são também conhecidos por “retorno de chamada web” (ou HTTP e, ainda, impulso API).
Os webhooks podem trazer vários benefícios, como informações em tempo real de que um evento ocorreu, sincronização dos dados e eficiência. À lista acrescentamos o fato de eles não utilizarem uma imensa quantidade de códigos complexos, o que torna a configuração mais rápida e simples.
Além disso, como eles normalmente utilizam HTTP, que já é um protocolo usado pela maioria dos sites, adicionar um webhook a um aplicativo não é algo que exija muito tempo e nem esforço.
Como funciona o webhook?
Um webhook reproduz automações pré-estabelecidas em sistemas ou ferramentas de chegadas. Sempre que ocorrer o gatilho que foi definido, a tecnologia notifica o usuário e executa a ação que foi também previamente programada.
Com relação aos dados, eles saem de um aplicativo X e vão para um aplicativo Y que os manipula. Vale destacar ainda que essa troca de informação acontece na web via um webhook URL.
Para melhor compreender, pense em um número de telefone. O aplicativo ou sistema receptor fornece o webhook URL, que seria como o número que o outro aplicativo ou sistema precisa ligar sempre que há um evento.
Também é importante entender que os dados fornecidos pelo webhook podem ter três formatos:
- JSON
- XML
- Dados de formulários (application / x-www-form-urlencoded ou multipart/form-data)
Como criar um webhook?
Para melhor ilustrar, mostraremos como criar webhook na Transfeera. Até o momento, só é possível ter uma URL inscrita por tipo de evento (campo object_types na API de registro de URLs de webhooks).
Todos os eventos são enviados através de uma requisição HTTP/HTTPS POST com o formato JSON no payload.
Seu endpoint precisa retornar um status code de sucesso na resposta, sendo (2xx) um formato válido e, assim, consideraremos como entregue. Caso contrário, tentamos entregar a notificação mais 2 vezes. Depois disso, não há mais tentativas de entregas da notificação deste evento.
Os eventos que podem ser criados são:
- Transfer: webhook contendo atualização de informações de uma transação de pagamento
- TransferRefund: webhook contendo atualização de informações sobre uma devolução de transação de pagamento
- CashIn: webhook contendo atualização de informações sobre um recebimento Pix
- CashInRefund: webhook contendo atualização de informações sobre uma devolução recebimento Pix
- PixKey: webhook contendo atualizações de status de chaves Pix
Para mais informações, consulte a documentação.
Fatores importantes para criar um webhook
Ao criar um webhook, leve em consideração fatores como:
- Segurança de dados: já que um webhook transmite dados de um ponto A ao B, é fundamental que esses mesmos dados sejam protegidos de invasores e hackers e que não se corrompam no caminho.
- Recebimento e armazenamento de dados: os webhooks devem ter um mecanismo de armazenamento de informações, o qual deve ser do tipo push. Também devem ter um mecanismo de recebimento de dados.
- Manipulação e escalabilidade: a tendência é que cada vez mais dados sejam agregados. Isso exige que webhooks sejam escaláveis, pois somente assim eles possibilitam a manipulação correta das informações.
Quais são as melhores práticas para implementar webhooks confiáveis?
As melhores práticas recomendadas para implementar webhooks confiáveis incluem:
- Ter uma validação dos dados recebidos para garantir que a proveniência seja de fonte esperada;
- Utilizar HTTPS para que os dados transitem com segurança;
- Validar a aplicação com testes no webhook e no sandbox de APIs;
- Manter o processamento de webhook no receptor eficiente para evitar timeouts e outros problemas;
- Verificar se o aplicativo, programa ou sistema está processando corretamente as informações dos eventos marcados no webhook. Eventos desnecessários devem ser desmarcados.
Quais as diferenças entre webhook e outros APIs tradicionais?
API é a sigla para Application Programming Interface que, em uma tradução para o português, significa “Interface de Programação de Aplicações”. Possui como objetivo permitir o intercâmbio de informações entre diferentes linguagens de programação e sistemas.
Assim como os webhooks, as APIs possibilitam a comunicação entre sistemas. No entanto, a diferença entre eles está na maneira pela qual recebem os dados. Explicando: para se manterem atualizadas, as APIs periodicamente necessitam extrair dados de um servidor e, para isso, é preciso haver uma solicitação.
Já com os webhooks não é assim que acontece. Para entender, eles são orientados a eventos (isto é, não dependem de uma solicitação). Além disso, são um endpoint HTTP, no qual o usuário recebe notificações em tempo real dos eventos que ocorrem em um servidor.
Ainda sobre as diferenças, entenda que uma API é o conjunto de regras e métodos com os quais podemos comunicar e usar esse serviço. Ou seja, é uma maneira de interagir com o webhook.
Em termos práticos, webhooks podem utilizar APIs do tipo REST, GraphQL, entre outras.
Como rastrear problemas em webhooks?
O principal ponto a se atentar é que, como os webhooks entregam dados para um aplicativo, ferramenta ou sistema, se houver algum erro nesses dados, eles poderão se perder. Além do mais, se o próprio app/ferramenta/sistema tiver erros, o webhook não trará as respostas esperadas.
Por essa razão, certifique-se sobre os dados e como o webhook reage às respostas que recebe.
Para rastrear os problemas em si, é importante manter registros detalhados de todas as notificações de webhook enviadas e recebidas, incluindo o código de resposta HTTP. Também faça o registro de erros, exceções ou problemas de processamento que possam ocorrer ao lidar com eles.
Quais são as considerações de segurança ao lidar com webhooks?
Como os webhooks utilizam uma URL fora do domínio SSL (ou seja, que é disponível publicamente), entre a mensagem enviada e a recebida não há criptografia. Isso explica a importância de garantir que a requisição venha de uma fonte segura e que o endpoint receba somente eventos legítimos.
Para isso, os tokens de autenticação são indicados, pois eles são verificados antes de processar o evento. Além disso, a autenticação básica, com login e senha, é igualmente essencial.
Falando ainda em autenticação como uma garantia a mais de segurança, o método mais popular usado em solicitações webhook é o código de autenticação de mensagem baseado em hash (HMAC). Nesse método, a origem e o destino dos dados compartilham a mesma chave secreta para assinar e validar solicitações de webhook.
Adicionalmente, como comentamos mais acima, para uma transmissão de dados segura, utilize o protocolo HTTPS.
Concluindo
Os webhooks são considerados ferramentas poderosas para o compartilhamento de informações. A Transfeera, uma fintech que fornece soluções de pagamentos para outras empresas, oferece o webhook para seus clientes.
Por exemplo, em uma transferência, o webhook é acionado assim que a ação é realizada. Ou seja, nossos clientes são notificados sempre que há uma entrada de dinheiro.
Sem uma webhook essa informação não aconteceria em tempo real. Seria necessário que alguém do financeiro consultasse o sistema da Transfeera para verificar quais foram os recebimentos e se uma determinada transferência já foi executada.
No entanto, com a webhook o cliente cadastra uma url na Transfeera e o sistema, por sua vez, manda uma mensagem para essa mesma url. Desse modo, o cliente ganha:
- Mais facilidade para fazer a conciliação;
- Mais agilidade no envio das informações;
- Mais rapidez nos processos que se seguem aos pagamentos de clientes, fornecedores etc.
A integração da plataforma da Transfeera é feita por meio de uma API. Para explorar as possibilidades das nossas APIs e ver como funciona a criação de webhooks no nosso sistema, convidamos você a acessar o Sandbox e:
- Realizar testes em nosso ambiente para validar as integrações com o seu sistema;
- Simular transações de pagamentos, validar dados bancários;
- Gerar QR Codes Pix;
- E muito mais.
