Webhooks
O Clickmax tem dois tipos de webhook: entrada (in), que recebe eventos de uma plataforma externa, e saída (out), que envia um evento do Clickmax para uma URL externa quando um gatilho acontece.
Papel exigido: membro autenticado do workspace. A gestão de webhooks fica na área de Integrações.
Direção
Valores aceitos ao criar um webhook de entrada.
Destinos aceitos ao criar um webhook de saída.
Gatilhos
Eventos que disparam um webhook de saída (campo trigger).
Cartão recusado x transação falhou
REFUSED_CARD dispara uma vez por tentativa de pagamento em que o cartão foi enviado à cobrança e recusado. Uma segunda tentativa do comprador com o mesmo cartão, alguns minutos depois, é uma nova recusa e dispara de novo.
Compra que nem chega à cobrança — cartão obrigatório não informado, produto sem estoque, conta do vendedor pendente, endereço de entrega faltando — não é recusa de cartão: dispara só TRANSACTION_FAILED. Pix e boleto que falham também usam apenas TRANSACTION_FAILED.
Venda ou fatura de renovação no SALE_MADE
SALE_MADE dispara na compra e também em cada fatura de renovação paga de uma assinatura, a partir da segunda cobrança. O campo isSubscriptionInvoice diferencia os dois casos: false na compra, true na fatura de renovação.
Nas faturas de renovação de assinaturas vendidas no seu checkout, o corpo traz também subscriptionId, subscriptionExternalId (código da assinatura no gateway), occurrence e purchaseDate (data da compra original). Nessas faturas, saleDate é a data da cobrança da parcela.
O campo occurrence é o número da cobrança informado pelo gateway e pode pular números, porque o gateway também conta o reenvio de uma cobrança vencida. Para saber em qual ciclo a assinatura está, conte as faturas recebidas com o mesmo subscriptionId.
Quando SUBSCRIPTION_CANCELLED dispara
Em qualquer cancelamento de assinatura, independentemente da origem: cancelamento pelo comprador, por você ou pelo suporte, cancelamento automático por falta de pagamento depois do período de tolerância, e o cancelamento que acompanha um reembolso.
Assinatura que chegou ao fim da duração contratada (última cobrança prevista do plano) não é cancelamento e não dispara este gatilho.
Quando um gatilho acontece, o Clickmax envia uma requisição para a URL da integração com o seguinte formato:
Autenticação
A requisição é autenticada pelo cabeçalho cm-token. No seu endpoint, compare o valor recebido com o token exibido na integração e recuse a requisição (por exemplo, com 401) se forem diferentes. O token é fixo por integração; não há assinatura HMAC do corpo.
Como identificar o evento
O corpo não traz o nome do gatilho. Uma mesma integração pode escutar vários gatilhos e todos chegam na mesma URL, então use uma destas opções para saber qual evento chegou:
- crie uma integração por gatilho, cada uma com uma URL diferente (por exemplo,
https://seu-sistema.com/webhook?evento=SALE_MADE);
- ou diferencie pelos campos do corpo, que mudam de um evento para outro (veja as tabelas abaixo).
Resposta, novas tentativas e desativação
- Qualquer resposta
2xx conta como entrega concluída (COMPLETED). O conteúdo da resposta é guardado no histórico.
- Qualquer outra resposta (como
4xx ou 5xx) ou falha de conexão gera nova tentativa. São até 3 tentativas por evento, com espera crescente entre elas (cerca de 10 e 20 segundos). Enquanto aguarda, o registro fica DELAYED; depois da última falha, FAILED.
- Se as 15 últimas tentativas da integração falharem, ela é desativada automaticamente. Corrija o endpoint, reative a integração e reenvie os registros pelo histórico.
- Responda rápido e processe o evento depois: o mesmo evento pode chegar mais de uma vez (por exemplo, num reenvio manual), então trate o corpo de forma idempotente, usando IDs como
transactionId ou leadId.
O formato acima vale para os destinos genéricos (Zapier, Make, n8n, Pluga, URL do seu sistema etc.). ActiveCampaign, Nota do Infoprodutor, Notazz, UTMify e VK Metrics recebem o evento já convertido para o formato e a autenticação exigidos por cada plataforma, e não seguem as tabelas abaixo.
Corpo de cada evento
Cada tabela lista os campos exatamente como chegam no JSON:
- Obrigatório: o campo sempre vem no corpo. Quando é
Não, o campo pode não existir no JSON.
- Aceita
null: o campo pode vir com o valor null.
- Pode vir vazio: o campo de texto pode vir como string vazia (
""), por exemplo quando o dado não foi coletado.
- Campos
pai.filho estão dentro de um objeto; campos pai[].filho estão em cada item de uma lista.
- Datas são strings ISO 8601 em UTC (por exemplo,
2026-01-15T14:30:00.000Z).
- Valores monetários são inteiros em centavos (
9700 = 97,00). A moeda não é enviada.
Os exemplos usam dados fictícios. São os mesmos corpos enviados pelo botão de teste da integração, exceto IDs e datas, que no teste são gerados na hora.
Lead criado e lead capturado
Gatilhos: LEAD_CREATED, LEAD_CAPTURED.
LEAD_CREATED dispara uma vez, quando o lead passa a existir. LEAD_CAPTURED dispara a cada captura, inclusive quando um lead que já existe preenche um formulário de novo. Campos sem valor no lead não vêm no corpo.
Exemplo de corpo:
{
"fullname": "Fullname",
"email": "example@email.com",
"telephone": "9538374457",
"pageId": "cc37fec6-85c0-423b-b704-a80d195d7fe9",
"pageUrl": "https://clickmax.io",
"pageName": "Page name",
"funnelId": "a01f1d8e-c418-4217-9d80-9b4a29438a52",
"funnelName": "Funnel name",
"utmSource": "source",
"utmMedium": "medium",
"utmCampaign": "campaign",
"utmTerm": "term",
"utmContent": "content",
"src": "vturb_vsl_01",
"sck": "lote2",
"capturedAt": "2026-01-15T14:30:00.000Z"
}
Venda realizada
Gatilhos: SALE_MADE.
Exemplo de corpo:
{
"email": "example@email.com",
"document": "12345678909",
"firstName": "First Name",
"lastName": "Last Name",
"phone": "5538933008932",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"address": "Avenida Paulista, 1000, Sala 123, Bela Vista, 01310-100",
"offerId": "cc37fec6-85c0-423b-b704-a80d195d7fe9",
"productId": "a01f1d8e-c418-4217-9d80-9b4a29438a52",
"productName": "Product Name",
"saleDate": "2026-01-15T14:30:00.000Z",
"price": 9700,
"utmSource": "source",
"utmMedium": "medium",
"utmCampaign": "campaign",
"utmTerm": "term",
"utmContent": "content",
"src": "vturb_vsl_01",
"sck": "lote2",
"pageUrl": "https://test.clickmax.io/test-clickmax",
"pageName": "Test Clickmax",
"gateway": "iopay",
"orderBumps": [
{
"offerId": "d3429377-199d-4075-aa4c-9a32d327a877",
"productId": "0b03581c-8f7e-4269-81a9-063f6e8ea6c0",
"price": 2700,
"productName": "Product Name"
}
],
"transactionId": "a19950fa-f965-4415-84d8-73e102a9ab7e",
"isSubscriptionInvoice": true,
"subscriptionId": "1fd8c3f0-8d15-4228-951f-f1d6c5df1015",
"subscriptionExternalId": "SUB-8F3K2L",
"occurrence": 3,
"purchaseDate": "2025-11-16T14:30:00.000Z"
}
Venda cancelada, reembolso e chargeback
Gatilhos: SALE_CANCELLED, REFUND_MADE, CHARGEBACK_REQUESTED.
Os três gatilhos enviam o mesmo corpo; o que muda é o motivo. Configure uma URL por gatilho para diferenciá-los.
Exemplo de corpo:
{
"buyerId": "cc37fec6-85c0-423b-b704-a80d195d7fe9",
"leadId": "a01f1d8e-c418-4217-9d80-9b4a29438a52",
"email": "example@email.com",
"name": "Buyer Name",
"phone": "5538933008932",
"document": "12345678900",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"address": "Avenida Paulista, 1000, Sala 123, Bela Vista, 01310-100",
"offerId": "d3429377-199d-4075-aa4c-9a32d327a877",
"productId": "0b03581c-8f7e-4269-81a9-063f6e8ea6c0",
"productName": "Product Name",
"price": 9700,
"transactionId": "a19950fa-f965-4415-84d8-73e102a9ab7e",
"gateway": "iopay",
"cancelledDate": "2026-01-15T14:30:00.000Z",
"utmSource": "source",
"utmMedium": "medium",
"utmCampaign": "campaign",
"utmTerm": "term",
"utmContent": "content",
"src": "vturb_vsl_01",
"sck": "lote2"
}
Assinatura iniciada
Gatilhos: SUBSCRIPTION_STARTED.
Exemplo de corpo:
{
"email": "example@email.com",
"document": "12345678900",
"firstName": "John",
"lastName": "Doe",
"phone": "5538933008932",
"offerId": "cc37fec6-85c0-423b-b704-a80d195d7fe9",
"orderBumps": [
{
"offerId": "a01f1d8e-c418-4217-9d80-9b4a29438a52",
"productId": "d3429377-199d-4075-aa4c-9a32d327a877",
"price": 2700,
"productName": "Product Name"
}
],
"transactionId": "0b03581c-8f7e-4269-81a9-063f6e8ea6c0",
"utmSource": "source",
"utmMedium": "medium",
"utmCampaign": "campaign",
"utmTerm": "term",
"utmContent": "content",
"src": "vturb_vsl_01",
"sck": "lote2"
}
Assinatura cancelada
Gatilhos: SUBSCRIPTION_CANCELLED.
Exemplo de corpo:
{
"buyerId": "cc37fec6-85c0-423b-b704-a80d195d7fe9",
"leadId": "a01f1d8e-c418-4217-9d80-9b4a29438a52",
"email": "example@email.com",
"name": "Buyer Name",
"telephone": "5538933008932",
"document": "12345678900",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"address": "Avenida Paulista, 1000, Sala 123, Bela Vista, 01310-100",
"productName": "Product Name",
"price": 9700,
"subscriptionStatus": "canceled",
"subscriptionId": "d3429377-199d-4075-aa4c-9a32d327a877",
"offerId": "0b03581c-8f7e-4269-81a9-063f6e8ea6c0",
"productId": "a19950fa-f965-4415-84d8-73e102a9ab7e",
"frequency": "monthly",
"gateway": "iopay",
"cancelledDate": "2026-01-15T14:30:00.000Z",
"utmSource": "source",
"utmMedium": "medium",
"utmCampaign": "campaign",
"utmTerm": "term",
"utmContent": "content",
"src": "vturb_vsl_01",
"sck": "lote2"
}
Carrinho abandonado
Gatilhos: ABANDONED_CART.
Exemplo de corpo:
{
"leadId": "cc37fec6-85c0-423b-b704-a80d195d7fe9",
"leadName": "Lead Name",
"leadEmail": "lead@email.com",
"leadDocument": "12345678909",
"leadCity": "City",
"leadTelephone": "5538933008932",
"leadWhatsappNumber": "5538933008932",
"offerId": "a01f1d8e-c418-4217-9d80-9b4a29438a52",
"offerName": "Meu produto",
"offerPrice": 9700,
"offerType": "software",
"ownerId": "d3429377-199d-4075-aa4c-9a32d327a877",
"projectId": "0b03581c-8f7e-4269-81a9-063f6e8ea6c0",
"productId": "a19950fa-f965-4415-84d8-73e102a9ab7e",
"abandonedDate": "2026-01-15T14:30:00.000Z",
"stage": "personal_data",
"utmSource": "source",
"utmMedium": "medium",
"utmCampaign": "campaign",
"utmTerm": "term",
"utmContent": "content",
"src": "vturb_vsl_01",
"sck": "lote2"
}
Cartão recusado
Gatilhos: REFUSED_CARD.
Exemplo de corpo:
{
"buyerId": "cc37fec6-85c0-423b-b704-a80d195d7fe9",
"leadId": "a01f1d8e-c418-4217-9d80-9b4a29438a52",
"offerId": "d3429377-199d-4075-aa4c-9a32d327a877",
"offerName": "Meu produto",
"offerPrice": 9700,
"offerType": "software",
"buyerEmail": "buyer@email.com",
"buyerName": "Buyer Name",
"buyerTelephone": "5538933008932",
"ownerId": "0b03581c-8f7e-4269-81a9-063f6e8ea6c0",
"projectId": "a19950fa-f965-4415-84d8-73e102a9ab7e",
"productId": "1fd8c3f0-8d15-4228-951f-f1d6c5df1015",
"refusedDate": "2026-01-15T14:30:00.000Z",
"failReason": "Cartão recusado pela operadora",
"utmSource": "source",
"utmMedium": "medium",
"utmCampaign": "campaign",
"utmTerm": "term",
"utmContent": "content",
"src": "vturb_vsl_01",
"sck": "lote2"
}
Transação falhou
Gatilhos: TRANSACTION_FAILED.
Exemplo de corpo:
{
"buyerId": "cc37fec6-85c0-423b-b704-a80d195d7fe9",
"leadId": "a01f1d8e-c418-4217-9d80-9b4a29438a52",
"offerId": "d3429377-199d-4075-aa4c-9a32d327a877",
"offerName": "Meu produto",
"offerPrice": 9700,
"offerType": "software",
"buyerEmail": "buyer@email.com",
"buyerName": "Buyer Name",
"buyerTelephone": "5538933008932",
"ownerId": "0b03581c-8f7e-4269-81a9-063f6e8ea6c0",
"projectId": "a19950fa-f965-4415-84d8-73e102a9ab7e",
"productId": "1fd8c3f0-8d15-4228-951f-f1d6c5df1015",
"paymentType": "credit",
"failedDate": "2026-01-15T14:30:00.000Z",
"failReason": "Falha ao processar a transação",
"utmSource": "source",
"utmMedium": "medium",
"utmCampaign": "campaign",
"utmTerm": "term",
"utmContent": "content",
"src": "vturb_vsl_01",
"sck": "lote2"
}
Pix ou boleto expirado ou vencido
Gatilhos: PIX_OR_BOLETO_EXPIRED_OR_OVERDUE.
Exemplo de corpo:
{
"buyerId": "cc37fec6-85c0-423b-b704-a80d195d7fe9",
"leadId": "a01f1d8e-c418-4217-9d80-9b4a29438a52",
"offerId": "d3429377-199d-4075-aa4c-9a32d327a877",
"offerName": "Meu produto",
"offerPrice": 9700,
"offerType": "software",
"buyerEmail": "buyer@email.com",
"buyerName": "Buyer Name",
"buyerDocument": "12345678909",
"buyerTelephone": "5538933008932",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"address": "Avenida Paulista, 1000, Sala 123, Bela Vista, 01310-100",
"ownerId": "0b03581c-8f7e-4269-81a9-063f6e8ea6c0",
"projectId": "a19950fa-f965-4415-84d8-73e102a9ab7e",
"productId": "1fd8c3f0-8d15-4228-951f-f1d6c5df1015",
"expiredDate": "2026-01-15T14:30:00.000Z",
"utmSource": "source",
"utmMedium": "medium",
"utmCampaign": "campaign",
"utmTerm": "term",
"utmContent": "content",
"src": "vturb_vsl_01",
"sck": "lote2"
}
Tag adicionada e tag removida
Gatilhos: TAG_ADDED, TAG_REMOVED.
Os campos de contato são do lead que recebeu ou perdeu a tag.
Exemplo de corpo:
{
"id": "cc37fec6-85c0-423b-b704-a80d195d7fe9",
"email": "example@email.com",
"name": "Buyer Name",
"telephone": "5538933008932",
"whatsappNumber": "5538933008932",
"secondaryEmail": "example2@email.com",
"nameTag": "Tag Name",
"colorTag": "1b0570"
}
Funil criado e funil excluído
Gatilhos: FUNNEL_CREATED, FUNNEL_DELETED.
Exemplo de corpo:
{
"name": "Funnel name",
"description": "Funnel description",
"funnelUrl": "new-project-5250.clickmax.localhost/funnel-name",
"path": "funnel-name",
"type": "sequentialSales",
"category": "basic"
}
Funil editado
Gatilhos: FUNNEL_EDITED.
Traz o funil inteiro antes (oldFields) e depois (newFields) da edição. Só dispara quando algum desses campos mudou.
Exemplo de corpo:
{
"oldFields": {
"name": "Old funnel name",
"description": "Old funnel description",
"funnelUrl": "new-project-5250.clickmax.localhost/old-funnel-name",
"path": "old-funnel-name",
"type": "sequentialSales",
"category": "basic"
},
"newFields": {
"name": "Funnel name",
"description": "Funnel description",
"funnelUrl": "new-project-5250.clickmax.localhost/funnel-name",
"path": "funnel-name",
"type": "sequentialSales",
"category": "basic"
}
}
Página excluída
Gatilhos: PAGE_DELETED.
Também dispara para cada página quando o projeto inteiro é excluído.
Exemplo de corpo:
{
"name": "Page name",
"slug": "page-slug",
"pageUrl": "https://test.clickmax.io/page-slug",
"type": "sales"
}
Projeto criado e projeto excluído
Gatilhos: PROJECT_CREATED, PROJECT_DELETED.
Exemplo de corpo:
{
"name": "Project name"
}
Status dos registros
Cada entrega gera um registro com um destes status.
Relacionados
Se não funcionou
- A plataforma recebe
401 no envio de entrada: o webhook está inativo, foi excluído, ou o token/assinatura não confere — veja Códigos de erro.
- Webhook de saída não chega ao destino: confira o status do registro e a resposta do endpoint em Códigos de erro.
- Dúvidas gerais sobre integrações: consulte as Perguntas frequentes.