A página de webhooks é o local onde o administrador pode cadastrar webhooks externos, onde esses ficam listados, podendo ser inativados, ativados e editados a qualquer momento. 

O webhook consiste em uma configuração que gera uma comunicação entre sistemas, que é disparada após eventos pré-determinados. A comunicação é disparada para um destino definido pelo vendedor e permite por exemplo, automatizar processos de emissão de notas fiscais, comunicação e outras automações de mercado.

Leia este artigo para saber como configurar esses webhooks no dashboard.

PASSO 1.

No dashboard, clique em TheBank > Webhooks > Criar webhook. 

PASSO 2.

O formulário de criação/edição de webhooks é bem simples e contém apenas os campos extritamente necessários para um webhook de qualidade. Os campos são:

1. Nome - Texto de no máximo 255 caracteres

2. URL - Destino que receberá o payload do webhook. Deve ser uma URL conforme formatação https://www.meudestino.com.br

3. Produtos - Aqui será apresentado todos os produtos cadastrados em seu dashboard

4. Eventos - Aqui será exibido todos os eventos possíveis como gatilho para o funcionamento deste webhook. A primeira opção, e opção que virá por padrão, sempre será “Todos os eventos”. Os eventos serão divididos em 4 grupos:

a) Transacionais: Vinculados aos status de uma transação (QR code gerado / Pagamento aprovado / Reembolsado);

b) Pedido: Webhooks enviados para informar alterações de status do pedido;

c) Acessos: Webhooks vinculados à liberação ou remoção de acesso do comprador;

d) Abandono de carrinho: Webhook vinculado à uma desistência de compra antes de um pedido ser concluído com sucesso.

5. Token de segurança - É um token gerado internamente e usado como chave de segurança. Usualmente este token é informado ao destino e enviado no payload do webhook, assim somente serão tomadas ações em webhooks que contiverem o token correto.

6. Botão criar/salvar webhook - O botão que conclui a criação ou edição de um webhook. Após clicar neste botão, uma mensagem de sucesso aparecerá e à partir deste momento as alterações já estão em funcionamento. 

Entenda com mais detalhes cada tipo de evento: 

1) Transacional: 

Todo evento transacional estará apto a realizar o envio de um webhook. Aqui trabalharemos com os eventos como gatilho e o que eles representarão para a comunicação.

Exemplo de um formato de payload de um webhook transacional: 

Os eventos de webhook transacionais são:

a) Pagamento com cartão de crédito iniciado;

b) Boleto gerado - Quando uma transação por boleto tiver sido gerada e estiver aguardando o pagamento;

c) Pix gerado - Quando uma transação por pix tiver sido gerada e estiver aguardando a conclusão do pagamento;

d) Transação aprovada - Quando a transação tiver sido concluída com sucesso;

e) Transação negada - Transação falhou (Erro digitação de cartão, recusa do banco ou cartão de crédito, pix ou boleto expiraram ou venceram sem pagamento);

f) Reembolsado - Quando a transação que gerou a ativação desse pedido for devolvida;

g) Pendente de reembolso - Quando o pedido de reembolso foi feito mas ainda não foi concluído;

h) Chargeback - Quando o reembolso está vinculado à um pedido de chargeback realizado pelo próprio comprador/aluno diretamente em seu cartão de crédito ou banco. 

2) Venda:

Os eventos de pedido poderão gerar webhooks de acordo com seus status.

Os webhooks de pedido serão:

a) Cancelada - quando uma compra é cancelada após aprovada (Quando o vendedor efetiva o cancelamento);

b) Expirada - Quando um pedido se encerra sem pagamentos aprovados.
1) Pedido com múltiplos meios de pagamento acontecerão quando o último status de aguardando falhar;
2) Para pedidos que tenham apenas transações de cartão de crédito, ela falhará após 60 minutos de inatividade no pedido;

c) Completa - Quando a garantia de devolução/reembolso daquela venda se encerra (Por padrão, completa-se o prazo de 7 dias após a compra).

3) Abandono de carrinho:

Este será um evento único e acontecerá sempre que uma seção de compra for criada e o comprador sair antes de iniciar um pedido formalmente.
Este webhook só será enviado no caso do comprador ter preenchido algum dado de contato dele (E-mail ou telefone). Assim o administrador poderá tentar reter este lead.

4) Liberação de acesso:

Esse grupo possui dois eventos:

a) Liberar acesso - Acontecerá sempre que um pagamento for aprovado. Caso o pedido tenha mais de um produto, serão enviados um webhook por produto vinculado ao pedido;

b) Remover acesso - Acontecerá sempre que um acesso precisar ser removido. Caso o pedido tenha mais de um produto, será enviado um webhook por produto. Ele deverá ser emitido em caso de cancelamento do pedido, reembolso, chargeback ou atingimento da data de expiração.

PERGUNTAS FREQUENTES: 

1) Posso ter dois webhooks com o mesmo nome?
Não. Os nomes dos seus webhooks precisarão ser diferentes um do outro.

2) Posso cadastrar eventos de todos os grupos no mesmo webhook?

Sim. Os gatilhos geram o envio, então no caso de selecionar todos os eventos, ao final da conclusão de uma compra você terá emitido webhook transacional, de pedido e de acesso.

3) Se eu criar um webhook para um produto, e ele tiver sido comprado no fluxo de order-bump, o que acontece?

Nesse caso o payload transacional será enviado da mesma forma, porém o produto que não está cadastrado será removido do payload. Desta forma o payload apresentará os dados completos da transação, os dados completos do produto cadastrado no webhook e nenhum dado do produto principal.

4) Caso o destino esteja com algum problema, há rententativas de envio?

Sim, o webhook espera receber um retorno 200, que é o código utilizado para transações com sucesso. Caso o retorno seja um código de erro, então ele será reenviado em 2min, 5min e 10 minutos. Se após a terceira retentativa ele ainda não tiver dado um código de aceite, então ele não será mais reenviado.
Ele só tentará ser reenviado em caso de retorno de erro, de forma que, se na segunda tentativa retornar aceite, então não terá terceira ou quarta tentativas.

PASSO 3.

Para desativar ou ativar os webhooks, basta ir até o webhook que deseja editar, ir até a parte de Status e movimentar o botão, como na imagem. 

PASSO 4.

Você também pode personalizar a visualização dos webhooks, clicando no botão Visualizar.