GG CheckoutHelp Center
IntegraçõesWebhooks

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.

Tela Webhooks com as abas Webhooks, Criar Webhook e Histórico de Webhook e dois cards de webhook com o nome, o endereço e os eventos de cada um

A tela Webhook

AbaO que tem
WebhooksUm 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 WebhookA lista dos webhooks em tabela, com Produtos, Nome e URL, e o botão Adicionar integração.
Histórico de WebhookAs 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

Painel Criar Webhook com os campos Nome da integração, URL da integração, Secret, Origem com as opções Checkout e API, Produtos e a lista de eventos
CampoO que faz
Nome da integraçãoNome do webhook no painel, com pelo menos 3 caracteres.
URL da integraçãoEndereço que recebe os avisos.
Secret (opcional)Segredo enviado junto com cada aviso, para o seu sistema confirmar que ele veio do ggCheckout.
OrigemCheckout, para os eventos das vendas dos checkouts, ou API, para as cobranças da API de pagamentos.
ProdutosNa origem Checkout, os produtos que disparam o webhook, ou Todos os produtos.
Ordens de cobrançaNa origem API, as ordens de cobrança que disparam o webhook. Sem seleção, vale para todas.
EventosOs 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

  1. Em Ferramentas > Webhook, abra a aba Criar Webhook e clique em Adicionar integração.
  2. Preencha Nome da integração e URL da integração.
  3. Preencha o Secret, se o seu sistema valida os avisos.
  4. Em Origem, mantenha Checkout.
  5. Em Produtos, escolha os produtos ou Todos os produtos.
  6. Em Eventos, marque os eventos que o seu sistema precisa receber.
  7. 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.

On this page