Mivvo / Produtores · Integrações

Documentação de Webhooks

Guia completo para receber eventos de vendas, assinaturas e trial em tempo real. Configure uma URL, escolha os eventos e receba payloads JSON assinados diretamente no seu servidor.

Eventos em tempo realAutenticação por tokenLogs e retentativas

Sumário

1. Introdução
2. Configuração
3. Eventos disponíveis
4. Estrutura do payload
5. Rastreamento e parâmetros de URL
6. Payloads de exemplo
7. Autenticação por token
8. Filtros por produto e oferta
9. Exemplos de código
10. Logs e retentativas
11. Boas práticas

Seção 01

Introdução

Webhooks permitem que você receba notificações em tempo real sobre eventos que acontecem na sua conta Mivvo. Quando um evento ocorre (como uma venda confirmada ou uma assinatura cancelada), a Mivvo envia uma requisição HTTP POST para a URL configurada, com os dados do evento no corpo da requisição.

Como funciona: Você configura uma URL no painel → Um evento acontece → A Mivvo envia um POST com o payload JSON → Seu servidor processa os dados.

Seção 02

Configuração

Para configurar um webhook na Mivvo:

1Acesse Integrações no menu lateral.
2Na seção Webhooks, clique em Novo Webhook.
3Dê um nome identificador (opcional).
4Insira a URL do seu servidor que receberá as notificações.
5Selecione os eventos que deseja receber.
6Opcionalmente, filtre por produto ou oferta específica.
7Opcionalmente, ative o token de autenticação.
8Clique em Criar.

Seção 03

Eventos disponíveis

Eventos de Venda

Evento	Descrição
`sale.pending`	Venda criada, aguardando pagamento (ex: PIX, boleto)
`sale.paid`	Pagamento confirmado
`sale.canceled`	Venda cancelada (ex: PIX expirado)
`sale.refunded`	Venda reembolsada
`sale.chargedback`	Chargeback recebido (disputa de cartão)
`sale.failed`	Pagamento recusado pela operadora
`sale.abandoned`	Carrinho abandonado (checkout iniciado mas não concluído)

Eventos de Assinatura

Evento	Descrição
`subscription.created`	Nova assinatura criada
`subscription.canceled`	Assinatura cancelada pelo comprador ou produtor
`subscription.invoice_paid`	Cobrança recorrente paga com sucesso
`subscription.reminder`	Lembrete 5 dias antes do vencimento
`subscription.due`	Cobrança venceu hoje
`subscription.overdue_5`	Cobrança atrasada há 5 dias
`subscription.overdue_10`	Cobrança atrasada há 10 dias
`subscription.overdue_30`	Cobrança atrasada há 30 dias
`subscription.inactive`	Assinatura ficou inativa
`subscription.auto_canceled`	Assinatura cancelada automaticamente por inadimplência

Eventos de Trial

Evento	Descrição
`trial.started`	Período de trial iniciado
`trial.expiring_soon`	Trial expirando em breve (2 dias antes do término)
`trial.expired`	Trial expirou (comprador converteu para pagante)
`trial.expired_unpaid`	Trial expirou e o comprador não pagou

Seção 04

Estrutura do payload

Todos os payloads seguem uma estrutura padronizada com os seguintes campos comuns:

Campo	Tipo	Descrição
`event`	string	Nome do evento (ex: sale.paid)
`timestamp`	string	Data/hora do evento (ISO 8601)
`data.sale_id`	string	ID único da venda
`data.sale_type`	string	"main" (produto principal) ou "bump" (order bump)
`data.is_order_bump`	boolean	true se o evento representa um order bump
`data.parent_sale_id`	string \| null	ID da venda principal — preenchido apenas quando is_order_bump = true
`data.amount`	number	Valor do produto em reais decimais (ex.: 27.90). NÃO inclui a taxa de serviço de R$ 0,99, juros de parcelamento no cartão nem o valor de order bumps
`data.installments`	number	Número de parcelas (1 em PIX/boleto)
`data.payment_method`	string	"credit_card", "pix" ou "boleto"
`data.customer`	object	Dados do comprador
`data.product`	object	Dados do produto
`data.offer`	object	Dados da oferta (id, name, price em reais decimais sem juros)
`data.bumps`	array	Lista de order bumps comprados junto (só em sale_type = main). Cada item: { sale_id, product, offer, price, amount }. [] se não houver bumps
`data.utms`	object	UTMs padrão capturados no checkout (utm_source, utm_medium, utm_campaign, utm_term, utm_content)
`data.url_params`	object	Todos os parâmetros da URL do checkout (inclui UTMs e customizados como sck, xcod, click_id)
`data.tracking`	object	Rastreamento do comprador: fbp, fbc, ip e user_agent (Meta CAPI / antifraude)

json· customer

{
  "name": "João Silva",
  "email": "joao@email.com",
  "phone": "11999998888",
  "document": "12345678900"
}

json· product

{
  "id": "uuid-do-produto",
  "name": "Curso de Marketing Digital"
}

json· offer

{
  "id": "uuid-da-oferta",
  "name": "Oferta Principal",
  "checkout_link_id": "abc123"
}

Seção 05

Rastreamento e parâmetros de URL

Novidade · Acréscimo aditivo

A partir de agora, todo webhook enviado pela Mivvo passa a incluir 3 novos objetos dentro de data: utms, url_params e tracking. Eles são capturados no momento em que o comprador chega ao checkout e ficam persistidos — reenviados mesmo em eventos assíncronos (PIX pago horas depois, renovações de assinatura, trials expirados).

data.utms

UTMs padrão capturados no checkout (source, medium, campaign, term, content).

data.url_params

Mapa com todos os parâmetros da URL, incluindo customizados (sck, xcod, click_id, ref).

data.tracking

fbp, fbc, ip e user_agent para Meta CAPI, antifraude e trackers server-side.

data.utms

Parâmetros UTM padrão capturados da URL do checkout. Quando o comprador chega sem UTMs, o objeto vem com todos os campos null — o objeto sempre existe.

Campo	Tipo	Descrição
`utm_source`	string \| null	Origem do tráfego (ex.: facebook, google)
`utm_medium`	string \| null	Meio (ex.: cpc, email)
`utm_campaign`	string \| null	Nome da campanha
`utm_term`	string \| null	Termo/palavra-chave
`utm_content`	string \| null	Variação de criativo/anúncio

json· Exemplo · data.utms

{
  "utm_source": "facebook",
  "utm_medium": "cpc",
  "utm_campaign": "black-friday-2026",
  "utm_term": "quiz-emagrecimento",
  "utm_content": "criativo-video-01"
}

data.url_params

Contém todos os parâmetros da query string do checkout — inclui os UTMs e qualquer parâmetro customizado que você esteja usando (sck, xcod, click_id, ref, cid, etc.). Sempre presente (pode ser {} se a URL não tinha parâmetros), repassa exatamente o que veio na URL — nada é filtrado.

json· Exemplo · data.url_params

{
  "utm_source": "facebook",
  "utm_medium": "cpc",
  "utm_campaign": "black-friday-2026",
  "sck": "abc123",
  "xcod": "afiliado-xyz",
  "click_id": "gclid-99887766",
  "ref": "parceiro-01"
}

Dica: use este objeto quando precisar de parâmetros que não sejam UTMs padrão — trackers externos, IDs de clique, códigos de afiliado próprios.

data.tracking

Dados de rastreamento do comprador, úteis principalmente para Meta Conversions API (CAPI) e antifraude.

Campo	Tipo	Descrição
`fbp`	string \| null	Cookie _fbp do Meta Pixel (browser ID)
`fbc`	string \| null	Cookie _fbc do Meta Pixel (click ID do anúncio)
`ip`	string \| null	IP real do comprador no momento do checkout
`user_agent`	string \| null	User-Agent do navegador do comprador

json· Exemplo · data.tracking

{
  "fbp": "fb.1.1719849600000.1234567890",
  "fbc": "fb.1.1719849600000.IwAR0abcd1234",
  "ip": "189.45.123.87",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
}

Campos podem vir null

Se o comprador estiver com bloqueadores de cookies, VPN, ou se o Meta Pixel não estiver instalado. Normalmente ip e user_agent sempre existem; fbp/fbc dependem do Pixel.

Como aparecem no payload

Os 3 blocos ficam dentro de data, ao lado dos campos que você já recebe hoje. Exemplo aplicado a sale.paid:

json· sale.paid — com utms, url_params e tracking

{
  "event": "sale.paid",
  "timestamp": "2026-07-02T14:30:00.000Z",
  "data": {
    "sale_id": "uuid-da-venda-principal",
    "sale_type": "main",
    "is_order_bump": false,
    "parent_sale_id": null,
    "status": "paid",
    "amount": 99.90,
    "installments": 3,
    "payment_method": "credit_card",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "phone": "11999998888",
      "document": "12345678900"
    },
    "product": { "id": "uuid-do-produto", "name": "Curso de Marketing Digital" },
    "offer": { "id": "uuid-da-oferta", "name": "Oferta Principal", "price": 99.90, "checkout_link_id": "abc123" },
    "bumps": [
      {
        "sale_id": "uuid-do-bump-1",
        "product": { "id": "uuid-produto-bump-1", "name": "Bônus VIP" },
        "offer": { "id": "uuid-oferta-bump-1", "name": "Bônus VIP" },
        "price": 27.90,
        "amount": 27.90
      }
    ],
    "utms": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01"
    },
    "url_params": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01",
      "sck": "abc123",
      "xcod": "afiliado-xyz",
      "click_id": "gclid-99887766",
      "ref": "parceiro-01"
    },
    "tracking": {
      "fbp": "fb.1.1719849600000.1234567890",
      "fbc": "fb.1.1719849600000.IwAR0abcd1234",
      "ip": "189.45.123.87",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
    }
  }
}

Integração recomendada

Rastreamento e Meta Conversions API

Os campos de data.tracking foram desenhados para você enviar eventos server-side para a Meta CAPI com deduplicação correta em relação ao Meta Pixel do navegador.

Fluxo típico para sale.paid:

1Receba o webhook sale.paid no seu servidor.
2Monte o evento Purchase da CAPI usando o mapeamento:
3Use data.sale_id como event_id para deduplicar com o pixel do navegador.

Campo Mivvo	Meta CAPI
`data.tracking.fbp`	user_data.fbp
`data.tracking.fbc`	user_data.fbc
`data.tracking.ip`	user_data.client_ip_address
`data.tracking.user_agent`	user_data.client_user_agent
`data.customer.email`	user_data.em (SHA-256)
`data.customer.phone`	user_data.ph (SHA-256)
`data.sale_id`	event_id (deduplicação)

O mesmo padrão vale para TikTok Events API, Google Enhanced Conversions e Kwai — todos aceitam IP, User-Agent e click ID equivalentes.

Eventos que incluem os novos blocos

Vendas

sale.pending
sale.paid
sale.canceled
sale.refunded
sale.chargedback
sale.failed / sale.refused
sale.abandoned

Assinaturas

subscription.created
subscription.canceled
subscription.invoice_paid

Trials

trial.started
trial.expiring_soon
trial.expired_unpaid

Order bumps enviados junto com a venda principal também carregam os mesmos 3 blocos, herdados da sessão de checkout.

Perguntas frequentes

Os UTMs são preservados em renovações de assinatura?›

Sim. As UTMs, url_params e tracking capturados no checkout original ficam persistidos na assinatura e são reenviados em todos os subscription.invoice_paid futuros.

E se o comprador entrar no checkout sem nenhum parâmetro?›

utms vem com todos os campos null, url_params vem como {}, e tracking vem com os campos que foi possível capturar (normalmente ip e user_agent sempre existem; fbp/fbc dependem do Meta Pixel).

Seção 06

Payloads de exemplo

Unidade monetária

Valores em reais decimais — nunca em centavos

Todos os campos monetários (amount, price, seller_amount, platform_fee) vêm em reais decimais — por exemplo, 27.90 (e nunca 2790).

O que NÃO entra em amount:

• Taxa de serviço de R$ 0,99 (paga pelo cliente).
• Juros de parcelamento no cartão (2x ou mais).
• Valor dos order bumps — esses vêm no array bumps[] da venda principal e em eventos próprios com is_order_bump = true.

Novos campos · Order bumps

Como identificar uma venda com order bump

Cada order bump gera seu próprio evento (sale.paid, sale.pending, etc.) com sale_id próprio. Todos apontam para a mesma parent_sale_id — o sale_id da venda principal. Escolha uma das estratégias abaixo para não processar em dobro:

Estratégia A

Compra agrupada

Leia data.bumps no evento onde sale_type = "main" e ignore eventos individuais com is_order_bump = true.

Estratégia B

Eventos individuais

Consuma todos os eventos e reconcilie cada bump com a venda principal pelo campo parent_sale_id.

json· sale.paid — Venda principal (com 1 order bump)

{
  "event": "sale.paid",
  "timestamp": "2026-07-02T14:30:00.000Z",
  "data": {
    "sale_id": "uuid-da-venda-principal",
    "sale_type": "main",
    "is_order_bump": false,
    "parent_sale_id": null,
    "status": "paid",
    "amount": 99.90,
    "installments": 3,
    "payment_method": "credit_card",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "phone": "11999998888",
      "document": "12345678900"
    },
    "product": { "id": "uuid-do-produto", "name": "Curso de Marketing Digital" },
    "offer": { "id": "uuid-da-oferta", "name": "Oferta Principal", "price": 99.90, "checkout_link_id": "abc123" },
    "bumps": [
      {
        "sale_id": "uuid-do-bump-1",
        "product": { "id": "uuid-produto-bump-1", "name": "Bônus VIP" },
        "offer": { "id": "uuid-oferta-bump-1", "name": "Bônus VIP" },
        "price": 27.90,
        "amount": 27.90
      }
    ],
    "utms": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01"
    },
    "url_params": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01",
      "sck": "abc123",
      "xcod": "afiliado-xyz",
      "click_id": "gclid-99887766",
      "ref": "parceiro-01"
    },
    "tracking": {
      "fbp": "fb.1.1719849600000.1234567890",
      "fbc": "fb.1.1719849600000.IwAR0abcd1234",
      "ip": "189.45.123.87",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
    }
  }
}

json· sale.paid — Evento individual de order bump

{
  "event": "sale.paid",
  "timestamp": "2026-07-02T14:30:00.000Z",
  "data": {
    "sale_id": "uuid-do-bump-1",
    "sale_type": "bump",
    "is_order_bump": true,
    "parent_sale_id": "uuid-da-venda-principal",
    "status": "paid",
    "amount": 27.90,
    "installments": 3,
    "payment_method": "credit_card",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "phone": "11999998888",
      "document": "12345678900"
    },
    "product": { "id": "uuid-produto-bump-1", "name": "Bônus VIP" },
    "offer": { "id": "uuid-oferta-bump-1", "name": "Bônus VIP", "price": 27.90 },
    "utms": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01"
    },
    "url_params": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01",
      "sck": "abc123",
      "xcod": "afiliado-xyz",
      "click_id": "gclid-99887766",
      "ref": "parceiro-01"
    },
    "tracking": {
      "fbp": "fb.1.1719849600000.1234567890",
      "fbc": "fb.1.1719849600000.IwAR0abcd1234",
      "ip": "189.45.123.87",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
    }
  }
}

json· sale.pending — Aguardando pagamento (PIX)

{
  "event": "sale.pending",
  "timestamp": "2026-07-02T14:30:00.000Z",
  "data": {
    "sale_id": "uuid-da-venda",
    "sale_type": "main",
    "is_order_bump": false,
    "parent_sale_id": null,
    "status": "pending",
    "amount": 49.00,
    "installments": 1,
    "payment_method": "pix",
    "customer": {
      "name": "Maria Santos",
      "email": "maria@email.com",
      "phone": "21988887777",
      "document": "98765432100"
    },
    "product": { "id": "uuid-do-produto", "name": "E-book Receitas Fitness" },
    "offer": { "id": "uuid-da-oferta", "name": "Oferta Especial", "price": 49.00, "checkout_link_id": "def456" },
    "bumps": [],
    "utms": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01"
    },
    "url_params": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01",
      "sck": "abc123",
      "xcod": "afiliado-xyz",
      "click_id": "gclid-99887766",
      "ref": "parceiro-01"
    },
    "tracking": {
      "fbp": "fb.1.1719849600000.1234567890",
      "fbc": "fb.1.1719849600000.IwAR0abcd1234",
      "ip": "189.45.123.87",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
    }
  }
}

json· sale.refunded — Reembolso

{
  "event": "sale.refunded",
  "timestamp": "2026-07-02T14:30:00.000Z",
  "data": {
    "sale_id": "uuid-da-venda",
    "sale_type": "main",
    "is_order_bump": false,
    "parent_sale_id": null,
    "status": "refunded",
    "amount": 99.90,
    "installments": 3,
    "payment_method": "credit_card",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "phone": "11999998888",
      "document": "12345678900"
    },
    "product": { "id": "uuid-do-produto", "name": "Curso de Marketing Digital" },
    "offer": { "id": "uuid-da-oferta", "name": "Oferta Principal", "price": 99.90, "checkout_link_id": "abc123" },
    "bumps": [],
    "utms": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01"
    },
    "url_params": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01",
      "sck": "abc123",
      "xcod": "afiliado-xyz",
      "click_id": "gclid-99887766",
      "ref": "parceiro-01"
    },
    "tracking": {
      "fbp": "fb.1.1719849600000.1234567890",
      "fbc": "fb.1.1719849600000.IwAR0abcd1234",
      "ip": "189.45.123.87",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
    }
  }
}

json· sale.abandoned — Carrinho abandonado

{
  "event": "sale.abandoned",
  "timestamp": "2026-07-02T14:30:00.000Z",
  "data": {
    "sale_id": null,
    "sale_type": "main",
    "is_order_bump": false,
    "parent_sale_id": null,
    "status": "abandoned",
    "amount": 199.00,
    "installments": 1,
    "payment_method": "pix",
    "customer": {
      "name": "Carlos Oliveira",
      "email": "carlos@email.com",
      "phone": "31977776666",
      "document": "55544433322"
    },
    "product": { "id": "uuid-do-produto", "name": "Mentoria Premium" },
    "offer": { "id": "uuid-da-oferta", "name": "Oferta de Lançamento", "price": 199.00, "checkout_link_id": "ghi789" },
    "bumps": [],
    "utms": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01"
    },
    "url_params": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01",
      "sck": "abc123",
      "xcod": "afiliado-xyz",
      "click_id": "gclid-99887766",
      "ref": "parceiro-01"
    },
    "tracking": {
      "fbp": "fb.1.1719849600000.1234567890",
      "fbc": "fb.1.1719849600000.IwAR0abcd1234",
      "ip": "189.45.123.87",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
    }
  }
}

json· subscription.created — Assinatura criada

{
  "event": "subscription.created",
  "timestamp": "2026-07-02T14:30:00.000Z",
  "data": {
    "sale_id": "uuid-da-venda",
    "subscription_id": "uuid-da-assinatura",
    "status": "active",
    "amount": 49.00,
    "installments": 1,
    "payment_method": "credit_card",
    "interval": "monthly",
    "customer": {
      "name": "Ana Costa",
      "email": "ana@email.com",
      "phone": "41966665555",
      "document": "11122233344"
    },
    "product": { "id": "uuid-do-produto", "name": "Comunidade VIP" },
    "offer": { "id": "uuid-da-oferta", "name": "Plano Mensal", "price": 49.00, "checkout_link_id": "jkl012" },
    "credentials": { "email": "ana@email.com", "password": "senha-gerada-123" },
    "utms": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01"
    },
    "url_params": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01",
      "sck": "abc123",
      "xcod": "afiliado-xyz",
      "click_id": "gclid-99887766",
      "ref": "parceiro-01"
    },
    "tracking": {
      "fbp": "fb.1.1719849600000.1234567890",
      "fbc": "fb.1.1719849600000.IwAR0abcd1234",
      "ip": "189.45.123.87",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
    }
  }
}

json· subscription.canceled — Assinatura cancelada

{
  "event": "subscription.canceled",
  "timestamp": "2026-07-02T14:30:00.000Z",
  "data": {
    "subscription_id": "uuid-da-assinatura",
    "status": "canceled",
    "amount": 49.00,
    "customer": {
      "name": "Ana Costa",
      "email": "ana@email.com",
      "phone": "41966665555",
      "document": "11122233344"
    },
    "product": { "id": "uuid-do-produto", "name": "Comunidade VIP" },
    "offer": { "id": "uuid-da-oferta", "name": "Plano Mensal", "price": 49.00, "checkout_link_id": "jkl012" },
    "utms": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01"
    },
    "url_params": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01",
      "sck": "abc123",
      "xcod": "afiliado-xyz",
      "click_id": "gclid-99887766",
      "ref": "parceiro-01"
    },
    "tracking": {
      "fbp": "fb.1.1719849600000.1234567890",
      "fbc": "fb.1.1719849600000.IwAR0abcd1234",
      "ip": "189.45.123.87",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
    }
  }
}

json· subscription.invoice_paid — Cobrança recorrente paga

{
  "event": "subscription.invoice_paid",
  "timestamp": "2026-07-02T14:30:00.000Z",
  "data": {
    "subscription_id": "uuid-da-assinatura",
    "sale_id": "uuid-da-venda",
    "status": "paid",
    "amount": 49.00,
    "installments": 1,
    "payment_method": "credit_card",
    "customer": {
      "name": "Ana Costa",
      "email": "ana@email.com",
      "phone": "41966665555",
      "document": "11122233344"
    },
    "product": { "id": "uuid-do-produto", "name": "Comunidade VIP" },
    "offer": { "id": "uuid-da-oferta", "name": "Plano Mensal", "price": 49.00, "checkout_link_id": "jkl012" },
    "utms": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01"
    },
    "url_params": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01",
      "sck": "abc123",
      "xcod": "afiliado-xyz",
      "click_id": "gclid-99887766",
      "ref": "parceiro-01"
    },
    "tracking": {
      "fbp": "fb.1.1719849600000.1234567890",
      "fbc": "fb.1.1719849600000.IwAR0abcd1234",
      "ip": "189.45.123.87",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
    }
  }
}

json· trial.started — Trial iniciado

{
  "event": "trial.started",
  "timestamp": "2026-07-02T14:30:00.000Z",
  "data": {
    "sale_id": "uuid-da-venda",
    "status": "trial",
    "amount": 0,
    "trial_days": 7,
    "trial_ends_at": "2026-07-09T14:30:00.000Z",
    "customer": {
      "name": "Pedro Souza",
      "email": "pedro@email.com",
      "phone": "51955554444",
      "document": "55566677788"
    },
    "product": { "id": "uuid-do-produto", "name": "Plataforma de Cursos" },
    "offer": { "id": "uuid-da-oferta", "name": "Trial 7 dias", "price": 99.00, "checkout_link_id": "mno345" },
    "credentials": { "email": "pedro@email.com", "password": "senha-gerada-456" },
    "utms": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01"
    },
    "url_params": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01",
      "sck": "abc123",
      "xcod": "afiliado-xyz",
      "click_id": "gclid-99887766",
      "ref": "parceiro-01"
    },
    "tracking": {
      "fbp": "fb.1.1719849600000.1234567890",
      "fbc": "fb.1.1719849600000.IwAR0abcd1234",
      "ip": "189.45.123.87",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
    }
  }
}

json· trial.expiring_soon — Trial expirando em breve

{
  "event": "trial.expiring_soon",
  "timestamp": "2026-07-07T10:00:00.000Z",
  "data": {
    "trial_id": "uuid-do-trial",
    "trial_days_remaining": 2,
    "trial_end": "2026-07-09T00:00:00.000Z",
    "customer": {
      "name": "Pedro Souza",
      "email": "pedro@email.com",
      "phone": "51955554444",
      "document": "55566677788"
    },
    "product": { "id": "uuid-do-produto", "name": "Plataforma de Cursos" },
    "offer": { "id": "uuid-da-oferta", "name": "Trial 7 dias", "price": 99.00 },
    "utms": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01"
    },
    "url_params": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01",
      "sck": "abc123",
      "xcod": "afiliado-xyz",
      "click_id": "gclid-99887766",
      "ref": "parceiro-01"
    },
    "tracking": {
      "fbp": "fb.1.1719849600000.1234567890",
      "fbc": "fb.1.1719849600000.IwAR0abcd1234",
      "ip": "189.45.123.87",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
    }
  }
}

json· trial.expired_unpaid — Trial expirado sem pagamento

{
  "event": "trial.expired_unpaid",
  "timestamp": "2026-07-09T14:30:00.000Z",
  "data": {
    "sale_id": "uuid-da-venda",
    "status": "expired",
    "amount": 99.00,
    "trial_days": 7,
    "customer": {
      "name": "Pedro Souza",
      "email": "pedro@email.com",
      "phone": "51955554444",
      "document": "55566677788"
    },
    "product": { "id": "uuid-do-produto", "name": "Plataforma de Cursos" },
    "offer": { "id": "uuid-da-oferta", "name": "Trial 7 dias", "price": 99.00, "checkout_link_id": "mno345" },
    "utms": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01"
    },
    "url_params": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday-2026",
      "utm_term": "quiz-emagrecimento",
      "utm_content": "criativo-video-01",
      "sck": "abc123",
      "xcod": "afiliado-xyz",
      "click_id": "gclid-99887766",
      "ref": "parceiro-01"
    },
    "tracking": {
      "fbp": "fb.1.1719849600000.1234567890",
      "fbc": "fb.1.1719849600000.IwAR0abcd1234",
      "ip": "189.45.123.87",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
    }
  }
}

Seção 07

Autenticação com token

Para garantir que as requisições vêm da Mivvo, você pode ativar a autenticação por token. Quando ativado, todas as requisições incluem o header:

X-Mivvo-Token: seu-token-unico-aqui

O token é gerado automaticamente para sua conta e pode ser copiado na configuração do webhook. No seu servidor, valide o token antes de processar o evento:

js· Validação de token

// Node.js — Validar token
const MIVVO_TOKEN = process.env.MIVVO_WEBHOOK_TOKEN;

app.post('/webhook', (req, res) => {
  const token = req.headers['x-mivvo-token'];
  if (token !== MIVVO_TOKEN) {
    return res.status(401).json({ error: 'Token inválido' });
  }
  // Processar evento...
  res.status(200).json({ received: true });
});

Seção 08

Filtros por produto e oferta

Você pode configurar um webhook para receber eventos apenas de produtos ou ofertas específicas. Isso é útil quando você tem múltiplos produtos e quer direcionar os eventos para endpoints diferentes.

Todos os produtos

Se nenhum produto for selecionado, o webhook recebe eventos de todos os seus produtos.

Produtos específicos

Selecione um ou mais produtos para filtrar os eventos.

Ofertas específicas

Filtre ainda mais por ofertas específicas dentro dos produtos selecionados.

Seção 09

Exemplos de código

js· webhook.js

const express = require('express');
const app = express();
app.use(express.json());

const MIVVO_TOKEN = process.env.MIVVO_WEBHOOK_TOKEN;

app.post('/webhook/mivvo', (req, res) => {
  // 1. Validar token (se configurado)
  const token = req.headers['x-mivvo-token'];
  if (MIVVO_TOKEN && token !== MIVVO_TOKEN) {
    return res.status(401).json({ error: 'Não autorizado' });
  }

  const { event, data } = req.body;

  // 2. Processar por tipo de evento
  switch (event) {
    case 'sale.paid':
      console.log('Venda confirmada!', data.customer.email);
      break;
    case 'sale.refunded':
      console.log('Reembolso!', data.customer.email);
      break;
    case 'subscription.created':
      console.log('Nova assinatura!', data.customer.email);
      break;
    case 'subscription.canceled':
      console.log('Assinatura cancelada!', data.customer.email);
      break;
    case 'trial.started':
      console.log('Trial iniciado!', data.customer.email);
      break;
    case 'trial.expiring_soon':
      console.log('Trial expirando em breve!', data.customer.email);
      break;
    case 'trial.expired_unpaid':
      console.log('Trial expirado!', data.customer.email);
      break;
    default:
      console.log('Evento não tratado:', event);
  }

  // 3. Responder rapidamente com 200
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook server rodando na porta 3000');
});

Seção 10

Logs e retentativas

Cada envio de webhook é registrado com os seguintes dados:

Status HTTP

O código de resposta do seu servidor (200, 500, etc.)

Tempo de resposta

Quanto tempo seu servidor levou para responder.

Payload enviado

O JSON completo que foi enviado.

Resposta

O corpo da resposta do seu servidor.

Você pode visualizar os logs de cada webhook na seção de Integrações do painel. Use o botão Teste ao lado de cada evento para enviar um payload de teste e verificar se sua integração está funcionando corretamente.

Seção 11

Boas práticas

Responda rapidamente (HTTP 200)

Retorne um status 200 o mais rápido possível. Se precisar de processamento pesado, coloque em uma fila e processe assincronamente.

Valide o token

Sempre valide o header X-Mivvo-Token para garantir que a requisição realmente veio da Mivvo.

Implemente idempotência

Use o sale_id ou subscription_id para evitar processar o mesmo evento duas vezes. Armazene os IDs processados e ignore duplicatas.

Use HTTPS

Configure sua URL de webhook com HTTPS para garantir que os dados trafeguem de forma segura.

Trate eventos críticos

Não esqueça de tratar sale.refunded e subscription.canceled para revogar acessos quando necessário.

Monitore os logs

Acompanhe periodicamente os logs no painel para identificar falhas de entrega e corrigi-las rápido.

Precisa de ajuda?

Dúvidas sobre integração de webhooks? Fale com a gente: suporte@mivvo.com.br.