[Webhooks] Boas práticas para melhor utilização

Com o objetivo de  mitigar falhas e otimizar o tempo de entrega dos Webhooks, este artigo foi criado para orientar sobre boas práticas.

Por que utilizar Webhooks ao invés de fazer consultas diárias na API?

Em alguns cenários, você precisará aguardar alguma ação do cliente final, como por exemplo o pagamento de uma fatura emitida.

Uma prática desaconselhável seria agendar consultas diárias na API da recorrência para saber qual é o status da fatura, pois não sabemos exatamente quando o cliente final fará a ação. Além de desperdiçar recursos de processamento, você também sofreria com o atraso entre o momento real do pagamento e da consulta via API.

Para resolver esse problema, inverte-se a responsabilidade da notificação: A Vindi avisará você quando alguma ação ocorrer.

Assim, você pode direcionar os seus recursos e requisições via API para suas vendas!

Quais os motivos da falha do meu Webhooks?

Os motivos podem ser variados, tais como: erros de timeout na espera da resposta (não obtivemos resposta do servidor), erros do servidor (não soube interpretar as informações do Webhooks e respondeu com algum código de erro), entre outros. Ao receber qualquer resposta de seu sistema com um código diferente de 2XX (200, 201, etc), ela será considerada como falha. 

A lista de código de status das respostas pode ser consultada aqui.

Como posso fazer o melhor uso do webhook?

- Cadastre os eventos de Webhooks de seu interesse para receber notificações de forma automática e assíncrona, evitando a necessidade de realizar consultas na API;

- Monitore se as URLs cadastradas estão ativas e aptas a receber informações dos Webhooks, caso não esteja edite/inative o Webhooks. O monitoramento pode ser feito checando em seu servidor quais códigos seu sistema está retornando aos Webhooks enviados;

- Verifique se o seu sistea está processando corretamente as informações dos eventos marcados no Webhooks . Desmarque os eventos que não são necessários para o seu sistema.

Por que a Vindi vai desligar os webhooks da recorrência com 100% de falha (nos últimos 30 dias)?

Hoje Webhooks com sucesso concorrem com os mesmos recursos de Webhooks com falha, logo Webhooks com falhas podem ser um empecilho e influenciar no tempo de entrega de outros Webhooks, sejam eles seus ou de outros clientes.

Atualmente, o processo de envio dos Webhooks pode ser realizado de 1 até 10 vezes (em casos de falha), onde a primeira é a tentativa de entrega e as outras 9 são retentativas do Webhooks que falhou, o que gera impacto direto no processamento de Webhooks saudáveis.

O que aparece na plataforma quando desligamos?

Em "Configurações > Webhooks" ele aparecerá como inativo.

Com esse desligamento, existe alguma ação inesperada do sistema? Preciso realizar alguma ação?

Iremos atuar somente em Webhooks que falham 100% das vezes, por isso a possibilidade de qualquer erro é irrisória.

Não é preciso realizar nenhuma ação, a não ser que queira editar a URL que já tenha apresentado erro. Caso queira,  você poderá reativar o Webhooks, mas é preciso garantir que as entregas serão processadas corretamente com sucesso. Se a reativação for feita, mas ainda assim o Webhooks continuar falhando repetidamente, inativaremos de forma automática novamente.

Quero reativar meu Webhooks. Como eu faço isso? 

Você pode reativar o Webhooks inativado, via plataforma, mas terá que corrigir e garantir o processamento dessas informações com sucesso.

Onde posso visualizar meus Webhooks ativos e inativos?

Poderá visualizar quais Webhooks estão ativos ou inativos na plataforma de recorrência em "Configurações > Webhooks".

Para testar a URL do seu Webhooks, bem como selecionar os eventos para notificação ou até mesmo ativar/inativar o próprio Wehooks , acesse a opção "Editar" (no ícone de configuração ao lado da coluna status).

Consigo visualizar os erros dos meus webhooks?

A partir da plataforma ainda não é possível visualizar qual URL ou quais eventos apresentam falhas, mas é possível testar a URL em "Configurações > Webhooks > Editar" ou cadastrando um novo webhook em "Configurações > Webhooks > Novo webhook". Ainda que a URL funcione corretamente, é preciso garantir que a resposta às informações enviadas nessa URL responda sempre com sucesso, pois pode ser que o seu servidor receba a informação mas não saiba processá-la corretamente, retornando um código de erro na resposta. Por isso é preciso que você gerencie todo o processamento da informação enviada.

Por que limitaram as informações em 10 cobranças nos eventos de webhooks de faturas pagas e faturas canceladas?

A limitação de 10 cobranças foi feita justamente para otimizar a velocidade de entrega dos Webhooks, deixando somente as informações relevantes para esses eventos em específico.

Se quer saber um pouco mais sobre conceitos, estrutura e como nossos Webhooks funcionam, acesse este artigo.