👍
Com o objetivo de mitigar falhas e otimizar o tempo de entrega dos webhooks, criamos esse guia 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 webhook?

Os motivos de falha do webhook 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 webhook 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 webhook 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 webhook. O monitoramento pode ser feito checando em seu servidor quais códigos seu sistema está retornando aos webhooks enviados.
Verifique se o seu sistema está processando corretamente as informações dos eventos marcados no webhook. 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 webhook 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?

Vamos 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 webhook, mas é preciso garantir que as entregas serão processadas corretamente com sucesso. Se a re-ativação for feita, mas ainda assim o webhook continuar falhando repetidamente, iremos inativar de forma automática novamente.

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

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

Onde posso visualizar meus webhooks ativos e inativos?

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

Para testar a URL do seu webhook, bem como selecionar os eventos para notificação ou até mesmo ativar/inativar o próprio webhook, 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 1o 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.