Webhooks
O webhook avisa outro sistema a cada evento de venda, com um POST em JSON para a URL cadastrada. Os webhooks valem para todos os checkouts da conta.
O webhook é um aviso automático que o ggCheckout envia a outro sistema quando acontece um evento, como um Pix pago ou um cartão recusado. O aviso é uma requisição POST com os dados do evento em JSON, enviada para a URL que você cadastrou. Os webhooks são configurados na tela Webhook e valem para todos os checkouts da conta. Na seção Webhook do editor do checkout, há só o atalho Configurar webhooks.
A tela Webhook
| Aba | O que tem |
|---|---|
| Webhooks | Um card por webhook, com o nome, a URL, os eventos escolhidos e o selo API nos webhooks da API de pagamentos. O ícone de olho abre o webhook para editar. |
| Criar Webhook | A lista dos webhooks em tabela, com Produtos, Nome e URL, e o botão Adicionar integração. |
| Histórico de Webhook | As entregas feitas, com ID do Pedido, Produto, Tipo, Data/Hora e Status. |
No histórico, o status é Sucesso, Erro Cliente, Erro Servidor ou Pendente. Ver Detalhes mostra a execução em quatro abas: Visão Geral, com o código HTTP, as tentativas e o tempo de resposta; Requisição, com a URL, os headers e o payload enviado; Resposta, com o que o seu servidor devolveu; e Técnico.
Campos do webhook
| Campo | O que faz |
|---|---|
| Nome da integração | Nome do webhook no painel, com pelo menos 3 caracteres. |
| URL da integração | Endereço que recebe os avisos. |
| Secret (opcional) | Segredo enviado junto com cada aviso, para o seu sistema confirmar que ele veio do ggCheckout. |
| Origem | Checkout, para os eventos das vendas dos checkouts, ou API, para as cobranças da API de pagamentos. |
| Produtos | Na origem Checkout, os produtos que disparam o webhook, ou Todos os produtos. |
| Ordens de cobrança | Na origem API, as ordens de cobrança que disparam o webhook. Sem seleção, vale para todas. |
| Eventos | Os eventos que geram aviso. Selecionar todos marca a lista inteira. |
A origem API tem eventos próprios e exige o Secret, que assina as entregas. Esses eventos estão descritos em Webhooks da API.
Ao editar um webhook antigo, o campo ID do produto no webhook escolhe entre Formato antigo e Formato novo. No formato antigo, product.id mantém o ID anterior do produto e o ID novo vai em idV2. No formato novo, product.id leva o ID novo.
Como criar um webhook
- Em Ferramentas > Webhook, abra a aba Criar Webhook e clique em Adicionar integração.
- Preencha Nome da integração e URL da integração.
- Preencha o Secret, se o seu sistema valida os avisos.
- Em Origem, mantenha Checkout.
- Em Produtos, escolha os produtos ou Todos os produtos.
- Em Eventos, marque os eventos que o seu sistema precisa receber.
- Clique em Criar. Antes de gravar, o ggCheckout envia um aviso de teste para a URL. Se a URL não responder, o webhook não é criado e a tela mostra o erro.
Desativação automática
Um webhook que falha 3 vezes seguidas é desativado automaticamente e passa a mostrar o selo Desativado. Para reativar, corrija a URL e salve de novo: o teste é refeito no salvamento. URLs que apontam para endereços não permitidos são bloqueadas, assim como as URLs da UTMify, que é integrada pela tela Métricas.
No painel
Ferramentas > Webhook, abas Webhooks, Criar Webhook e Histórico de Webhook.
Bling
A integração com o Bling emite NF-e e NFS-e na sua conta Bling a cada venda aprovada. A conexão é feita por autorização no Bling, sem senha.
Estrutura do payload
O payload do webhook é o JSON enviado por POST a cada evento: o evento, o comprador, o pagamento, os produtos, o webhook e as UTMs da visita.