FAQ - Webhooks
Encontre respostas para perguntas frequentes e problemas relacionados com envio de webhooks.
Nesta página:
Como funciona o webhook?
O que são envios simultâneos e como configurar corretamente?
Meu número de vendas recentes excedeu o máximo de envios simultâneos configurado, o que acontece nesse caso?
Tenho um sistema próprio, posso receber os webhooks do Guru?
Posso enviar o webhook para ferramentas de automatização como Zapier e afins?
Por que não consigo adicionar ou ativar um webhook?
O webhook ainda não foi enviado, o que aconteceu?
O webhook foi enviado, mas os dados não aparecem no sistema de destino. O que devo fazer?
Como funciona o webhook?
O webhook é uma funcionalidade que envia automaticamente notificações para um sistema externo toda vez que um evento específico acontece. No Guru, você pode enviar notificações de venda e de assinaturas.
Quando sua conta possui webhooks ativos e a condição de envio do webhook for atendida, o Guru envia uma notificação para o endereço de destino configurado contendo os dados da respectiva venda ou assinatura.
Os envios vão para uma fila e, em poucos minutos, chegam ao sistema de destino. O histórico do envio é gravado na auditoria da respectiva venda ou assinatura para eventual consulta no futuro.
O que são envios simultâneos e como configurar corretamente?
Envios simultâneos indica o número máximo de envios que o Guru pode fazer ao mesmo tempo para um sistema externo. Esse recurso é útil para evitar sobrecarregar o servidor de destino com muitas requisições ao mesmo tempo.
Como funciona na prática
Por exemplo: digamos que você configurou o máximo de 10 envios simultâneos e está no meio de um lançamento com muitas vendas acontecendo ao mesmo tempo. Nesse caso, o sistema vai se comportar da seguinte maneira:
Obtém e envia as próximas 10 vendas* da lista de uma única vez para o servidor de destino.
Se ainda existirem itens na fila para enviar: aguarda 10 segundos e executa novamente o passo 1.
(*) Ao invés de 10 vendas, podem ser 10 assinaturas.
Como configurar corretamente
Por padrão, recomendamos configurar 5 envios simultâneos.
Quanto maior for a capacidade do seu servidor, maior é a quantidade de envios simultâneos que você pode configurar. Seja cautoloso com esse limite, pois um número elevado de envios simultâneos pode acarretar erros de envio do webhook (respostas HTTP 500, 502 ou 503 vindas do servidor de destino).
Na dúvida, converse com seu especialista de infraestrutura para saber o número adequado de envios simultâneos que deve configurar.
Caso possua webhook de venda e de assinatura ativos para o mesmo endereço de destino, tenha atenção redobrada ao máximo de envios configurado em cada webhook. Pois um lançamento que envolva o envio destes 2 webhooks ao mesmo tempo pode sobrecarregar seu servidor rapidamente.
Meu número de vendas recentes excedeu o máximo de envios simultâneos configurado, o que acontece nesse caso?
Neste caso, sua fila de envio será partida em blocos menores de acordo com o número máximo de envios simultâneos configurado. Cada bloco será enviado com um espaço de 10 segundos entre eles.
Exemplo: digamos que você tenha 55 vendas pendentes de envio e seu nº máximo de requisições seja de 10 envios. Nesse caso, o Guru vai organizar o envio dos webhooks em 6 blocos. Os envios serão da seguinte forma:
Bloco 1: envia 10 vendas, espera 10 segundos;
Bloco 2: envia +10 vendas, espera 10 segundos;
Bloco 3: envia +10 vendas, espera 10 segundos;
Bloco 4: envia +10 vendas, espera 10 segundos;
Bloco 5: envia +10 vendas, espera 10 segundos;
Bloco 6: envia as 5 vendas restantes.
Tenho um sistema próprio, posso receber os webhooks do Guru?
Sim, pode. Para isso vai precisar da ajuda de um desenvolvedor para construir um sistema web capaz de receber o webhook, ler o conteúdo do post e, em seguida, gravar ou atualizar seu banco de dados.
Compartilhe essa documentação com o seu desenvolvedor.
Posso enviar o webhook para ferramentas de automatização como Zapier e afins?
Sim, pode. No entanto, você deve ter em mente que essas ferramentas não costumam armazenar o conteúdo recebido em uma base de dados.
Como o webhook é disparado toda vez que uma venda ou assinatura é atualizada no sistema (mesmo sem haver alteração de dados), você corre o risco de disparar a mesma ação várias vezes para a mesma venda ou assinatura ao usar essas ferramentas.
O ideal é que a ferramenta de destino faça um controle básico das notificações recebidas para tomar ações somente quando se tratar de um item novo ou quando houver alteração em um dado específico.
Por que não consigo adicionar ou ativar um webhook?
Cada plano possui um limite máximo de webhooks ativos.
Se você está no período de testes, é permitido ativar até 2 webhooks. Se você já é assinante, pode ser necessário fazer um upgrade para a categoria Plus 2 ou Plus 3.
Consulte os limites operacionais de cada plano nesse link.
O webhook ainda não foi enviado, o que aconteceu?
Se você está no meio de um lançamento e houve um volume muito alto de vendas, pode ser que elas ainda estejam na fila para envio. Se você não está em lançamento, pode ser a fila de envios do Guru esteja temporariamente sobrecarregada.
Aguarde pelo menos 30 minutos e verifique na auditoria da respectiva venda ou assinatura se o envio foi realizado. Se o problema persistir, contacte nosso time de suporte.
O webhook foi enviado, mas os dados não aparecem no sistema de destino. O que devo fazer?
O sistema de destino é responsável por processar e registrar localmente o webhook enviado pelo Guru.
O Guru envia a notificação para a plataforma de destino minutos após a venda ou assinatura correspondente ser atualizada. Em alguns casos, os dados podem demorar um pouco mais para aparecer no sistema de destino em função de sobrecarga no servidor.
Caso os dados enviados não apareçam em até 30 minutos no sistema de destino, execute os procedimentos a seguir:
1 - Verifique o resultado do envio do webhook
No detalhe da venda ou assinatura correspondente, acesse a opção Auditoria e procure por um item recente1 que indique um envio do webhook para a plataforma de destino. De acordo com o resultado do processamento do envio, o ícone exibido pode ser azul (sucesso) ou vermelho (erro).
1 Os eventos da auditoria são listados do mais recente para a mais antigo.
1.1 - Envio realizado com sucesso
Nesse caso, pode ser que o sistema de destino esteja enfrentando alguma instabilidade nos servidores e o processamento das notificações recebidas do Guru foi impactado. Aguarde pelo menos 30 minutos e consulte novamente o sistema para ver se a situação foi normalizada.
Se após 30 minutos os dados da venda ou assinatura não constarem no sistema de destino, contacte o suporte desta ferramenta para verificar porque os dados enviados pelo Guru ainda não está sendo exibidos.
1.2 - Houve erro no envio
Nesse caso, você deve clicar na auditoria e verificar qual o erro está descrito. Na maioria das vezes, o erro exibido é retornado pelo sistema de destino. Tente analisar o erro1 retornado para identificar qual suporte (Guru ou sistema de destino) deverá contactar.
Se o erro exibido for um código HTTP 500, 502 ou 503 pode significar que o servidor está sobrecarregado. Neste caso, verifique o número de envios simultâneos configurado ou contacte o suporte da ferramenta de destino para saber o que aconteceu.