O que é?
Um "webhook" é um método de comunicação entre sistemas online, no qual um aplicativo ou serviço pode enviar automaticamente informações para outro aplicativo ou serviço quando eventos específicos ocorrem.
Os webhooks são amplamente utilizados para integração entre diferentes serviços da web, automatizando processos e permitindo uma comunicação mais eficiente entre aplicativos e plataformas. Sempre que um evento relevante ocorre no sistema emissor, ele envia um HTTP POST para a URL do webhook no sistema receptor.
Quer saber um pouco mais sobre webhooks de forma geral? Só acessar esse nosso blog!
Configuração
As URLs e eventos de webhook Vindi devem ser configuradas via plataforma. Assim que configurados os eventos que você deseja receber, as notificações serão sempre enviadas para a URL cadastrada, evitando assim consultas diárias ao webservices para verificar o status do evento, bem como o desperdício de recursos de processamento (acesse nosso artigo com boas práticas de webhook vindi).
Para realizar a configuração de webhooks basta acessar a plataforma Vindi > Configurações no menu à esquerda > clicar em Webhooks.
Após, clique em Novo Webhook, em seguida:
- Com a URL em mão, acesse webhooks na aba integrações em suas configurações, teste a URL que irá receber as notificações.
- Ao testar a URL com sucesso, selecione todos os eventos que você deseja receber notificações. Veja abaixo todos os eventos que temos na plataforma. (Para garantir o êxito do teste, realizamos uma requisição de verificação na URL cadastrada. Se a URL não retornar um código de status na faixa 2XX, não será possível salvar as informações na plataforma.)
Formato e método de envio
Todas as requisições geradas a partir de webhooks são efetuadas com o método POST, com o conteúdo no corpo (body) da requisição no formato JSON, incluindo os seguintes headers:
Content-Type: application/json; charset=UTF-8
User-Agent: Vindi-Hookshot/1.0
A plataforma espera que sua aplicação responda com o código HTTP 2XX (200, 201, etc) em no máximo 20 segundos. Códigos de redirecionamento (3XX) não serão seguidos e serão considerados como falha.
Ao criar o webhook, efetuamos uma requisição teste para verificar a URL que foi cadastrada. Caso sua URL retorne um código diferente de 2XX, não será possível salvá-lo na plataforma.
Caso seja necessário, consulte a lista de endereços IP de origem para webhooks.
Retentativas
A plataforma Vindi realizará até 8 tentativas de envio caso o seu sistema esteja inacessível ou responda com um código HTTP diferente de 2XX. Essas retentativas serão feitas em intervalos progressivos ao longo de aproximadamente 48 horas. Após esse período, caso a requisição não tenha sido bem-sucedida, a Vindi a descartará, sendo necessário realizar o envio manual da mesma.
As requisições podem chegar até seu servidor em uma ordem diferente do disparo. Dependendo da ação desejada, recomendamos que você faça uma consulta à API no momento em que receber o webhook para saber se as informações recebidas são as mais recentes.
Uma boa prática é armazenar localmente o conteúdo do webhook antes de processá-lo, uma vez que não é possível reenviá-los após o seu endpoint ter respondido de forma positiva com um código HTTP 2XX.
Conteúdo da requisição
O conteúdo da requisição estará contido em seu no corpo (body), no formato JSON:
{
"event":{
"type":"subscription_created",
"created_at":"2014-10-02T22:35:57.477-03:00",
"data":{
"subscription":{
{...}
}
}
}
}
O conteúdo do atributo data irá depender do tipo de evento enviado e respeitará o mesmo formato da API REST.
Eventos
Os seguintes eventos podem ser habilitados pelo painel de administração:
|
EVENTO |
TYPE |
DATA |
|
Assinatura Cancelada |
subscription_canceled |
subscription |
|
Assinatura Efetuada |
subscription_created |
subscription |
|
Assinatura Reativada |
subscription_reactivated |
subscription |
|
Cobrança Emitida |
charge_created |
charge |
|
Cobrança Estornada |
charge_refunded |
charge |
|
Cobrança Cancelada |
charge_canceled |
charge |
|
Cobrança Rejeitada |
charge_rejected |
charge |
|
Fatura Emitida |
bill_created |
bill |
|
Fatura Paga |
bill_paid |
bill |
|
Fatura Cancelada |
bill_canceled |
bill |
|
Fatura Visualizada |
bill_seen |
bill |
|
Período Criado |
period_created |
period |
|
Pendência Gerada |
issue_created |
issue |
|
Perfil de Pagamento Criado |
payment_profile_created |
payment_profile |
|
Mensagem Visualizada |
message_seen |
message |
|
Nota Fiscal Emitida |
invoice_issued |
invoice |
|
Perfil de Pagamento Renovado |
payment_profile_renewed |
payment_profile |
Allow list e segurança
Apesar da plataforma enviar os webhooks por meio de endereços IP específicos, para garantir a autenticidade das chamadas você deve configurar o usuário e senha na URL ou incluir um parâmetro secreto que seja validado do seu lado.
Exemplo com usuário e senha (HTTP Basic):
https://usuario:senha@www.empresa.com/webhook
Exemplo com parâmetro secreto:
https://www.empresa.com/webhook?secret=fo9graB5ids9
Apesar da plataforma suportar o envio para endereços HTTP, recomendamos fortemente que seu endpoint suporte HTTPS. Não é possível configurar portas diferentes de 80 (HTTP) ou 443 (HTTPS).
Caso opte por receber os webhooks da Vindi via HTTPS, você deverá usar um certificado emitido por uma autoridade certificadora reconhecida, ou seja, o certificado do seu servidor não deverá ser autoassinado.
TLS mútuo
Opcionalmente você poderá informar um certificado cliente para garantir a origem dos webhooks. A plataforma Vindi apresentará este certificado na requisição ao seu servidor, sendo responsabilidade do mesmo aceitar ou recusar a requisição. Este certificado pode ser autoassinado.
Esta técnica também é conhecida como 2-way TLS ou MTLS. É importante não confundir o certificado do seu servidor com o certificado cliente.
Cross Site Request Forgery (CSRF) em aplicações Rails, Django, etc.
Aplicações desenvolvidas com Ruby on Rails ou Django costumam embutir uma proteção automática contra CSRF. Embora seja uma boa prática, você precisará desabilitar esta proteção no endpoint onde deseja receber as requisições da Vindi.
Rails:
protect_from_forgery :except => :webhook
Django:
@csrf_exempt
def webhook(request):
Para mais informações sobre este assunto, consulte a documentação do Rails ou do Django. Para outros frameworks, busque na documentação pela sigla CSRF.
Testes
Antes de apontar o webhook para seu ambiente de produção, recomendamos testá-lo com o RequestBin. Esta ferramenta gera uma URL temporária onde você pode inspecionar as requisições realizadas pela Vindi.
Para direcionar testes de webhooks para o ambiente de desenvolvimento em seu próprio computador, recomendamos as ferramentas ngrok ou UltraHook.
Comentários
6 comentários
Recomendo o ngrok. Tive problemas com o UltraHook pois se contiver algum caracter especial no corpo da resposta, ele apresenta um erro e falha.
O desenvolvedor do UltraHook respondeu o seguinte:
The server side piece cant handle the unicode characters right now. This is a known issue that will get fixed in a future release.
In the mean time, you can use an alternative service like ngrok.com
Quando são emitidos eventos do tipo 'issue_created'?
To chocado com a oboscuridade dessa api... quais dados vem no webhook alem do event type? Gente, pra que cortar essas informações? Onde tem mais informações sobre o webhook... Documentação ta péssima
CodeMarket,
O retorno do webhook da Vindi é sempre a própria entidade. Ex: ações do tipo Fatura Criada e Fatura Paga, virá o dado da própria Fatura, ações do tipo Cobrança Criada/Rejeitada/Cancelada virá a própria Cobrança.
Recomendo muito você usar o ngrok para conseguir intercepatar de forma muito prática os dados do Webhook. Você baixa e executa o programa ngrok, ele gera uma URL randômica, e esta que você coloca na sua de retorno do Webhook de Sandbox da Vindi. Aí é só fazer diversas ações pelo próprio painel da Vindi e você irá coletar diversos eventos pelo ngrok, totalmente gratuito.
https://ngrok.com
A melhor dica que eu posso dar por ora é: lembre-se que ela envia os eventos Webhook fora de ordem, ficando ao critério de nós desenvolvedores reodernamos na nossa ponta caso necessário.
Onde tem os campos do evento? Não se acha em canto algum essa documentação.
Você pede pro webhook fazer um teste e ele manda um JSON mais incompleto ainda:
{'event': {'type': 'test', 'created_at': '2020-05-20T10:41:05.296-03:00', 'data': {'quote': {'content': 'It works!'}}}}"O conteúdo do atributo
datairá depender do tipo de evento enviado", sim, mas qual é o conteúdo pra cada evento? Quais chaves podemos esperar pra cada evento?Documentação mandou um abraço.
Olha, gente, queria dar parabéns pra vocês pelo artigo. Não sei se é porque eu já trabalho com webhooks faz algum tempo, e estou acostumado, mas não tive problema algum.
Abri o RequestBin, gerei uma URL nova, cadastrei ela nas configurações do sandbox da Vindi para Fatura Paga, usei o cartão de teste da master e o evento foi certinho, na estrutura que tá ali em cima.
Talvez o que tenha ficado não tão claro pro pessoal assim é que as reticências ("...") que estão ali no parâmetro data se referem justamente ao payload referente ao endpoint documentado em https://vindi.github.io/api-docs/dist/, mas, nada de novo.
Parabéns pela integridade no ambiente, povo!
Artigo fechado para comentários.