Como configurar um webhook na Celetus?
webhook integração token api-token eventos teste de webhook apps
Em Apps, abra Webhooks e clique em Novo Webhook. Informe o Nome, a URL do webhook (o endereço do seu sistema que vai receber os avisos), escolha o produto e marque ao menos um evento. Antes de salvar, use Testar Webhook para enviar uma mensagem fictícia e ver o código de resposta do seu sistema.
Um webhook é um aviso automático que a Celetus envia para o seu sistema (uma planilha automatizada, um CRM, um aplicativo próprio) toda vez que algo acontece em uma venda, como um Pix gerado ou uma compra aprovada. Para receber esses avisos, você cadastra o endereço do seu sistema e escolhe quais eventos quer receber. Este artigo mostra o cadastro e o teste. Para saber o que cada evento envia, veja Quais eventos e dados o webhook envia?. Para a lista do que a Celetus conecta, veja Quais integrações a Celetus oferece?.
O que preciso ter antes de começar?
- Uma URL pública em https do seu sistema que aceite receber dados por POST (um tipo de requisição em que a Celetus envia o conteúdo da mensagem). Endereços de uso interno, como
localhostou redes privadas, não recebem webhook. - Saber qual produto e quais eventos você quer acompanhar.
- Um jeito de conferir o que chega no seu sistema (o painel da ferramenta que recebe, ou o registro de acessos do seu servidor).
Como cadastro um webhook?
Passo a passo
- No menu lateral do painel, clique em Apps e abra o card Webhooks.
- Na tela Webhooks, clique em Novo Webhook. Abre a janela Criar Webhook.
- Preencha o Nome. É só para você reconhecer o webhook na lista e no histórico.
- Em URL do Webhook, cole o endereço do seu sistema, começando por
https://. - Em Produto, deixe Todos para receber de todos os seus produtos ou escolha um produto específico.
- Marque os eventos que quer receber (veja a seção abaixo).
- Clique em Salvar. A tela mostra
Concluído com sucessoe o webhook aparece na lista, com as colunas Produto, Nome e Ações.
Se faltar algo, o painel avisa e não salva: É necessário informar um nome, É necessário informar uma URL, URL inválido, Informe uma URL https pública para o webhook. (quando o endereço não é https ou não é público) ou Selecione no mínimo um evento.
O que significa cada campo?
| Campo | Para que serve |
|---|---|
| Nome | Identifica o webhook na lista, no histórico de envios e no conteúdo da mensagem. |
| URL do Webhook | Endereço do seu sistema que recebe as mensagens. |
| Token | Código da sua conta que a Celetus envia junto de cada mensagem, no cabeçalho Api-Token, para o seu sistema conferir que o aviso veio da Celetus. Aqui ele só é exibido e copiado (botão de copiar ao lado do campo). |
| Quantidade de tentativas | Quantas vezes a Celetus tenta enviar a mesma mensagem quando o seu sistema não responde com sucesso. Escolha na lista. |
| Produto | Todos ou um produto só. |
| Enviar para os orderbumps | Order bump é uma oferta extra exibida no checkout. Com Enviar para os orderbumps ligado, a Celetus faz envios por produto da compra que esteja no escopo deste webhook. Para incluir o principal e os extras, confira Produto: selecionar só o principal não inclui automaticamente os extras. Desligado, o envio considera o produto principal. Veja Como criar um order bump na Celetus?. |
| Enviar para vendas de afiliados | No webhook do produtor, inclui também as compras feitas pelo link de afiliados. Se desligar, essas compras não disparam o webhook do produtor. Em um webhook novo, a opção já vem ligada. |
| Evento | Quais acontecimentos da venda viram mensagem. Há o link [Selecionar todos os eventos]. |
Quais eventos eu marco?
Marque os eventos que o seu sistema deve tratar. Depois, confira em Webhooks Enviados quais eventos chegaram ao destino. Em resumo:
- Compra aprovada: o pagamento foi confirmado. É o evento mais usado para liberar acesso ou registrar a venda.
- Pix gerado, Boleto gerado e Aguardando pagamento: o comprador gerou o pagamento, que ainda não foi pago. Veja O que significam aprovada, aberta, abandonada e reembolsada?.
- Compras abandonadas: quem começou o checkout e saiu sem finalizar. Veja Como recuperar vendas de carrinho abandonado?.
- Os demais (recusa, reembolso, estorno, assinaturas e afiliação) estão explicados, um a um, em Quais eventos e dados o webhook envia?.
Como testo o webhook antes de usar?
O teste envia mensagens fictícias para a URL que você informou, sem depender de uma venda real.
Passo a passo
- Na janela Criar Webhook (ou Editar Webhook, se já salvou), clique em Testar Webhook.
- Na janela Testar Webhook, confira a URL do Webhook, o Produto e os eventos. O teste manda uma mensagem para cada evento marcado.
- Leia o aviso
Será enviado um webhook de teste com dados fictícios.e clique em Testar Webhook. - Na janela Resultado, veja um selo com o código de resposta para cada evento, ao lado do nome do evento.
O que significa o resultado do teste?
| Selo | O que indica |
|---|---|
| 200 Sucesso (qualquer código que começa com 2) | O seu sistema recebeu e respondeu com sucesso. |
| Redirecionamento (começa com 3) | O endereço respondeu mandando a Celetus para outro lugar. A Celetus não acompanha o redirecionamento: cadastre a URL final. |
| Erro do Cliente (começa com 4), como 404 Servidor ou método não encontrado | O endereço existe, mas recusou ou não achou a rota: confira o caminho da URL, se a rota aceita POST e se ela exige alguma autenticação. |
| Erro do Servidor (começa com 5) | O seu sistema falhou ao processar. Veja o registro de erros do seu lado. |
| Sem Resposta | A Celetus não conseguiu entregar o teste: a URL não é uma página https pública, o servidor está fora do ar ou demorou demais. |
- O teste não grava o webhook: depois de testar, clique em Salvar (na janela Criar Webhook ou Editar Webhook).
- O Token enviado no teste é o mesmo das mensagens reais. Se o seu sistema só aceita o
Api-Tokencorreto, o teste também serve para conferir isso. - Teste com um evento de cada vez quando quiser saber qual deles o seu sistema recusa.
Use Testar Webhook com dados fictícios e confira o código devolvido pelo destino. Esse teste não aparece em Webhooks Enviados: o histórico registra os envios gerados pelos eventos.
Como edito ou excluo um webhook?
Na lista, a coluna Ações tem o ícone de lápis (editar) e o de lixeira (excluir). Editar abre a mesma janela, agora chamada Editar Webhook. Ao excluir, o painel pergunta Deseja realmente deletar o webhook? antes de confirmar.
O webhook está cadastrado, mas nada chega. E agora?
Veja Meu webhook não foi entregue: o que fazer?. Ele ensina a ler o histórico em Webhooks Enviados, entender cada código e, depois de corrigir o destino, reenviar um envio.
Se mesmo assim travar, fale com o suporte informando o nome do webhook, o produto, o evento e o horário do envio. Nunca envie o Token.