Receber eventos da sua loja com webhooks

Neste artigo mostraremos como configurar webhooks para que a sua loja avise os seus próprios sistemas (um ERP, um CRM, um sistema de faturamento) sempre que uma venda for registrada.

Quando acontece um evento no qual você se inscreveu, a Publica.la envia uma requisição POST assinada, com os dados em formato JSON, para a URL que você indicar. Os webhooks estão disponíveis para todas as lojas e substituem o webhook de venda anterior, com várias vantagens: você pode ter até 10 destinos, cada um com a sua própria chave e os seus próprios eventos, e cada aviso inclui uma chave para evitar que seja processado duas vezes.

Antes de começar​

• Somente os administradores da loja podem gerenciar os webhooks. Os administradores de plano não têm acesso a esta seção.
• Sua loja pode ter até 10 endpoints. Um endpoint é cada URL do seu sistema que recebe os avisos.
• A URL deve ser pública: use http ou https, a porta 80 ou 443 e um endereço que não seja interno. Não seguimos redirecionamentos. Recomendamos https para que os dados trafeguem criptografados.

Eventos disponíveis​

Uma compra nova gera os dois eventos, e eles podem chegar em qualquer ordem. Para saber se uma cobrança é uma renovação, confira o campo charge.recurring_cycle do evento Cobrança paga: 1 é a primeira cobrança de uma assinatura, um número maior que 1 é uma renovação e null é uma compra de pagamento único.

Criar um endpoint​

1. Acesse o Painel de Controle e vá em Configurações > Webhooks.

2. Clique em Adicionar endpoint e preencha os dados:

• Nome: opcional. Ajuda a diferenciar os endpoints.
• URL: o endereço do seu sistema que receberá um POST para cada evento.
• Eventos: marque Pedido pago, Cobrança paga ou ambos.
• Ativo: deixe ativado para começar a receber os avisos. Se você desativar, o endpoint fica pausado.

3. Clique em Salvar. Você verá o aviso "Endpoint criado" e um quadro com a chave de assinatura do endpoint, um código de 64 caracteres que você usará para conferir que os avisos vêm da Publica.la.

Enviar um teste​

Para conferir que o seu sistema recebe os avisos, abra o menu do endpoint e clique em Enviar teste. Enviamos um exemplo do primeiro evento em que o endpoint está inscrito, com os cabeçalhos e a assinatura reais, mas com dados fictícios. Você verá o aviso "Evento de teste na fila" e, em instantes, a tentativa aparece em Entregas recentes (clique em Atualizar).

• Você pode enviar até 5 testes por minuto por endpoint. Se passar do limite, o painel informa quantos segundos esperar.
• O teste é tentado uma única vez, é enviado mesmo que o endpoint esteja pausado ou desabilitado e não conta para a desativação automática.
• A chave de idempotência dele começa com test:, para que você o diferencie de um aviso real.

Conferir as entregas recentes​

Abaixo da lista de endpoints, a seção Entregas recentes mostra as últimas 50 tentativas de entrega, mantidas por 30 dias. Cada tentativa mostra a data, o endpoint, o evento, o status, o número da tentativa, o código de resposta e a duração. Os status são:

• Entregue: o seu sistema respondeu com um código 2xx.
• Falhou: a tentativa falhou e será repetida enquanto restarem tentativas.
• Ignorada: não foi enviada porque o endpoint estava pausado, desabilitado ou excluído, ou porque o evento já tinha chegado a esse endpoint.

Gerenciar seus endpoints​

No menu de cada endpoint você pode:

• Editar: alterar o nome, a URL ou os eventos. Se você mudar a URL, a contagem de falhas é zerada e um endpoint desabilitado é habilitado novamente.
• Pausar / Retomar: parar de enviar avisos e voltar a enviá-los. Os eventos que acontecerem enquanto o endpoint estiver pausado são descartados, não são guardados para envio posterior.
• Rotacionar chave de assinatura: gerar uma chave nova. A anterior deixa de funcionar imediatamente, então atualize o seu sistema antes ou logo depois.
• Habilitar novamente: em um endpoint desabilitado, o painel mostra o último erro e permite habilitá-lo de novo.
• Excluir: apagar o endpoint. Pedimos uma confirmação porque é imediato e não pode ser desfeito: o endpoint deixa de receber eventos e as entregas dele deixam de ser exibidas.

O que o seu sistema recebe​

Cada aviso chega como um POST com um corpo JSON e estes cabeçalhos:

Algumas recomendações para a sua equipe técnica:

• Verifique a assinatura com a chave de assinatura antes de processar o aviso, e rejeite os que tenham um carimbo de data/hora com mais de 5 minutos de diferença.
• Responda com um código 2xx em menos de 10 segundos. Qualquer outra resposta é considerada uma falha.
• Evite duplicidades com X-Pla-Idempotency-Key: você pode receber o mesmo aviso mais de uma vez e a ordem entre os eventos não é garantida.

Os detalhes da assinatura, os campos de cada evento e um exemplo de verificação estão na documentação técnica de webhooks.

Novas tentativas e desativação automática​

Se o seu sistema não responder com um código 2xx, tentamos a entrega novamente até 12 vezes ao longo de cerca de 70 horas, com esperas cada vez mais longas (1 minuto, 5 minutos, 15 minutos, 1 hora, 3 horas, 6 horas e depois 12 horas).

Um endpoint é desabilitado automaticamente quando as suas últimas 5 entregas esgotaram todas as tentativas e ele não teve nenhuma entrega bem-sucedida nas últimas 72 horas. Enquanto estiver desabilitado, ele não recebe nada: os eventos novos são descartados e não enviamos nenhum aviso por e-mail. O painel o mostra como Desabilitado até você habilitá-lo novamente.

Migrar do webhook de venda anterior​

O webhook de venda anterior (o que é configurado em Configurações > Integrações) continua funcionando por enquanto, mas está obsoleto. Você pode manter os dois ativos ao mesmo tempo: crie seus novos endpoints, confira se o seu sistema os processa bem e só então desative o anterior. Tenha em mente estas diferenças:

• O webhook anterior enviava uma requisição para cada produto pago. Agora você recebe um único evento Cobrança paga por cobrança, com todos os pagamentos em data.payments.
• A assinatura deixou de ser um token JWT: agora é uma assinatura HMAC-SHA256 do corpo, no cabeçalho X-Pla-Signature.
• Renovações, cobranças de frete e resgates do Publica One chegam como eventos Cobrança paga.

O guia completo está na documentação técnica. Se você ainda usa o webhook anterior, consulte Configurar Webhooks.

Perguntas frequentes​

Posso enviar cada evento para um sistema diferente? Sim. Crie um endpoint por sistema (até 10) e marque em cada um apenas os eventos de que ele precisa. Cada endpoint tem a sua própria chave de assinatura.

Perdi a chave de assinatura. Posso vê-la de novo? Não, ela só é exibida ao criar o endpoint e ao rotacioná-la. Use Rotacionar chave de assinatura para gerar uma nova e atualize-a no seu sistema.

Meu endpoint parou de receber avisos. O que confiro? Abra Configurações > Webhooks e confira se o endpoint está pausado ou Desabilitado. Se estiver, corrija o problema no seu sistema, use Enviar teste e habilite-o novamente. As Entregas recentes mostram o último erro.

Como testo sem programar nada? Você pode usar um serviço que recebe requisições, como o webhook.site, que fornece uma URL pública temporária. Lembre que qualquer pessoa com essa URL pode ver os dados que chegarem, inclusive dados reais de vendas: exclua o endpoint ao terminar.

Ao salvar, a URL é rejeitada. Por quê? A URL deve ser pública, começar com http:// ou https:// e usar a porta 80 ou 443. Endereços privados ou locais não são aceitos.

O teste falha com um código 3xx. O que faço? O seu sistema está redirecionando. Não seguimos redirecionamentos, então configure a URL final exata.

Vou receber os eventos que aconteceram enquanto o endpoint estava pausado ou desabilitado? Não. Esses eventos são descartados e não são reenviados.

Recursos úteis​

• Documentação técnica de webhooks
• Configurar Webhooks (webhook de venda anterior)

Esperamos que este tutorial tenha sido simples de seguir. Se tiver dúvidas, escreva para [email protected].