Webhooks

Sistema de Webhooks configurável via UI para eventos de negócio (CRM/analytics).

Webhooks permitem que sua aplicação receba notificações automáticas sempre que um evento relevante acontece, como criação de vendas, pagamentos ou cancelamentos.

Assim, os dados chegam em tempo real, eliminando a necessidade de consultas constantes à API.

Webhooks funcionam como chamadas HTTP automáticas enviadas para um endpoint da sua aplicação sempre que um evento ocorre.

Nesses casos, é feita uma requisição POST com um payload em JSON, permitindo que os dados sejam processados imediatamente, sem necessidade de consultas recorrentes à API.

Eventos disponíveis

Os webhooks são enviados sempre que ocorre uma mudança de estado relevante no sistema.

Ao configurar a integração, você pode escolher quais eventos deseja receber, garantindo que sua aplicação processe apenas o que for necessário.

Eventos disponíveis

LEAD_CREATED — Lead criado

SALE_CREATED — Venda aprovada

SALE_CANCELED — Venda cancelada

PRODUCT_CREATED — Produto criado

PRODUCT_UPDATED — Produto atualizado

OFFER_CREATED — Oferta criada

OFFER_UPDATED — Oferta atualizada

VOUCHER_CREATED — Voucher criado

VOUCHER_UPDATED — Voucher atualizado

ORDER_DECLINED — Venda recusada

SUBSCRIPTION_UPDATED — Assinatura atualizada

SUBSCRIPTION_CANCELED — Assinatura cancelada

INVOICE_PAID — Fatura paga

INVOICE_REFUNDED — Reembolso

CONTACT_UPDATED — Contato atualizado

Configuração do Webhook

No menu lateral, acesse Webhooks e clique em Criar webhook.

Informe um nome de identificação, selecione os produtos associados, configure a URL de destino, o header e o token de autenticação, e marque os eventos desejados entre os disponíveis.

Antes de concluir a criação, utilize o botão Testar Webhook para enviar eventos de exemplo para a URL informada e validar se sua aplicação está recebendo e processando corretamente as notificações.

Um webhook já configurado pode ser editado, desativado (sem excluir) ou excluído a qualquer momento na mesma tela, na lista de webhooks já criados.

Cada webhook é enviado com um header de autenticação, cujo nome e valor (token) você mesmo define ao criar o webhook — não há um nome de header fixo. Valide esse header antes de processar o evento. Não há assinatura/HMAC do corpo da requisição: o token no header é o único mecanismo de verificação, então trate-o como um segredo (não exponha a URL do webhook nem o token) e rejeite qualquer chamada em que o header não bata com o valor configurado.

Segurança

Use HTTPS na URL de destino. A plataforma não bloqueia URLs http://, mas enviar o token de autenticação e os dados do payload sem TLS expõe ambos a interceptação — trate http:// como não seguro para produção.

Alguns payloads incluem dados sensíveis (CPF em contact.cpf, bandeira e dígitos parciais do cartão em payment_details.card_brand/card_first_digits/card_last_digits). Trate esses dados conforme a LGPD e as políticas de segurança da sua aplicação (evite logar o payload bruto, restrinja acesso ao armazenamento).

Estrutura do payload

Todos os eventos enviados possuem um conjunto de campos padrão que permitem identificar e rastrear o webhook recebido.

event_type: indica o tipo do evento disparado (ex: lead_created, sale_created).

event_id: identificador único do evento, útil para controle de idempotência e prevenção de processamento duplicado.

occurred_at: data e hora em que o evento ocorreu, no formato ISO 8601 (UTC).

Esses campos estão presentes em todos os webhooks e permitem que sua aplicação reconheça o evento antes de processar os dados específicos.

Período de venda da oferta

Toda oferta (offer e offers[]) traz o período de venda em dois campos e o limiar do contador em um terceiro. Eles vêm em todo evento que traz oferta.

available_from: data de início de venda da oferta, em ISO 8601 (UTC). null = a oferta não tem data de início.

available_until: data limite de venda da oferta, em ISO 8601 (UTC). null = a oferta não tem data limite.

urgency_time_threshold_minutes: minutos antes de available_until em que o contador da oferta começa a aparecer no checkout. null = durante todo o período.

Limite de vendas do produto

Todo produto (product e products[]) traz o limite de vendas. No SALE_CREATED, o bloco product traz também a quantidade de vagas ocupadas.

sales_limit: limite de vendas do produto, número inteiro. null = o produto não tem limite. Vem em todo evento que traz produto.

sold_count: só no SALE_CREATED. São as vagas ocupadas do produto: vendas pagas mais vendas aguardando pagamento criadas nos últimos 7 dias, de qualquer meio de pagamento (PIX ou boleto gerado, cartão em processamento), já incluindo a venda notificada. Renovações, vendas recusadas, canceladas e estornadas não entram.

O sold_count é lido no momento do envio do webhook, não no instante da venda. Com compras quase simultâneas, a venda que atinge o limite pode chegar com sold_count acima de sales_limit. Use o campo para comparar com o limite, não como a posição da venda.

sold_count vem null quando o produto não tem limite ou quando a contagem estava indisponível no envio.

Campos monetários

Todos os campos monetários dos webhooks (amount_total, comission, iva, amount/mercury_fee/interest/discount em payment_details, refunded_amount/discount_amount/original_amount em faturas) estão em reais, com até duas casas decimais.

Métodos de pagamento

O campo payment_method pode receber os seguintes valores: credit-card, nu-pay, pix, bank-slip, apple-pay, google-pay, cheque.

O valor cheque aparece em invoice.payment_method quando a fatura é baixada manualmente com cheque (ver Fatura paga).

Carteira digital

Compras pagas por carteira digital chegam com o payment_method da própria carteira:

Valor	Significado
`apple-pay`	Compra paga com Apple Pay
`google-pay`	Compra paga com Google Pay

Mudança de comportamento: essas compras costumavam chegar como credit-card. Se a sua integração compara payment_method com credit-card para identificar pagamento com cartão, inclua também apple-pay e google-pay — caso contrário essas vendas deixam de ser reconhecidas.

Atenção: nesses métodos, card_brand, card_first_digits, card_last_digits, card_exp_month e card_exp_year chegam como null. Isso é esperado — a cobrança usa um token da carteira, não o número do cartão, e esses dados não são repassados para nós. Use o payment_method para reconhecer o caso em vez de tratar como dado faltando.

Os valores de carteira aparecem nos eventos que carregam payment_details (SALE_CREATED e ORDER_DECLINED) e em invoice.payment_method dos eventos de fatura (INVOICE_PAID e INVOICE_REFUNDED).

{
  "event_type": "lead_created",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2025-11-24T14:03:22Z",
  ...
}

Lead criado (LEAD_CREATED)

{
  "event_type": "lead_created",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2025-11-24T14:03:22Z",
  "origin": "mercury",
  
  "lead": {
    "id": "ld_123",
    "name": "Fulano",
    "email": "fulano@email.com",
    "phone": "+5527999999999",
    "voucher_code": null,
    "created_at": "2025-11-24T14:03:22Z"
  },
  
  "offer":{
    "id": "off_456",
    "short_id": "P001",
    "name": "Black Friday",
    "is_active": true,
    "external_id": "LMS_CODE",
    "product_id": "prd_789",
    "product_name": "Curso X",
    "profiles": 1,
    "plan_type": "yearly",
    "available_from": "2026-10-01T03:00:00.000Z",
    "available_until": "2026-10-31T02:59:59.000Z",
    "urgency_time_threshold_minutes": 60,
    "created_at": "2025-11-24T14:03:22Z",
    "updated_at": "2025-11-24T14:03:22Z"
  },
  
  "tracking_parameters":{
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "utm_id": null,
    "utm_source_platform": null,
    "utm_marketing_tactic": null,
    "utm_creative_format": null,
    "ga_client_id": null,
    "gclid": null
  },
  "metadata": {}
}

Produto criado (PRODUCT_CREATED)

{
  "event_type": "product_created",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2025-11-24T14:03:22Z",
  "origin": "mercury",
  "product": {
    "id": "prd_789",
    "name": "Curso X",
    "code": "curso-x",
    "is_active": true,
    "checkoutGTM": null,
    "type": "course",
    "logoUrl": null,
    "sales_limit": 50,
    "created_at": "2025-11-24T14:03:22Z",
    "updated_at": "2025-11-24T14:03:22Z"
  },
  "metadata": {}
}

Produto atualizado (PRODUCT_UPDATED)

{
  "event_type": "product_updated",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2025-11-24T14:03:22Z",
  "origin": "mercury",
  "product": {
    "id": "prd_789",
    "name": "Curso X Atualizado",
    "code": "curso-x",
    "is_active": true,
    "checkoutGTM": null,
    "type": "course",
    "logoUrl": null,
    "sales_limit": 50,
    "created_at": "2025-11-24T14:03:22Z",
    "updated_at": "2025-11-24T14:03:22Z"
  },
  "metadata": {}
}

Oferta criada (OFFER_CREATED)

{
  "event_type": "offer_created",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2025-11-24T14:03:22Z",
  "origin": "mercury",
  "product": {
    "id": "prd_789",
    "name": "Curso X",
    "code": "curso-x",
    "is_active": true,
    "checkoutGTM": null,
    "type": "course",
    "logoUrl": null,
    "sales_limit": 50,
    "created_at": "2025-11-24T14:03:22Z",
    "updated_at": "2025-11-24T14:03:22Z"
  },
  "offer": {
    "id": "off_456",
    "short_id": "P001",
    "name": "Black Friday",
    "is_active": true,
    "external_id": "LMS_CODE",
    "product_id": "prd_789",
    "product_name": "Curso X",
    "profiles": 1,
    "plan_type": "yearly",
    "available_from": "2026-10-01T03:00:00.000Z",
    "available_until": "2026-10-31T02:59:59.000Z",
    "urgency_time_threshold_minutes": 60,
    "created_at": "2025-11-24T14:03:22Z",
    "updated_at": "2025-11-24T14:03:22Z"
  },
  "metadata": {}
}

Oferta atualizada (OFFER_UPDATED)

{
  "event_type": "offer_updated",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2025-11-24T14:03:22Z",
  "origin": "mercury",
  "product": {
    "id": "prd_789",
    "name": "Curso X",
    "code": "curso-x",
    "is_active": true,
    "checkoutGTM": null,
    "type": "course",
    "logoUrl": null,
    "sales_limit": 50,
    "created_at": "2025-11-24T14:03:22Z",
    "updated_at": "2025-11-24T14:03:22Z"
  },
  "offer": {
    "id": "off_456",
    "short_id": "P001",
    "name": "Black Friday Atualizada",
    "is_active": true,
    "external_id": "LMS_CODE",
    "product_id": "prd_789",
    "product_name": "Curso X",
    "profiles": 1,
    "plan_type": "yearly",
    "available_from": "2026-10-01T03:00:00.000Z",
    "available_until": "2026-10-31T02:59:59.000Z",
    "urgency_time_threshold_minutes": 60,
    "created_at": "2025-11-24T14:03:22Z",
    "updated_at": "2025-11-24T14:03:22Z"
  },
  "metadata": {}
}

Voucher criado (VOUCHER_CREATED)

{
  "event_type": "voucher_created",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2025-11-24T14:03:22Z",
  "origin": "mercury",
  "voucher": {
    "id": "vch_123",
    "type": "percentage",
    "code": "WELCOME10",
    "value": 10,
    "startAt": "2025-11-24T14:03:22Z",
    "endAt": null,
    "created_at": "2025-11-24T14:03:22Z",
    "updated_at": "2025-11-24T14:03:22Z"
  },
  "products": [
    {
      "id": "prd_789",
      "name": "Curso X",
      "code": "curso-x",
      "is_active": true,
      "checkoutGTM": null,
      "type": "course",
      "logoUrl": null,
      "sales_limit": 50,
      "created_at": "2025-11-24T14:03:22Z",
      "updated_at": "2025-11-24T14:03:22Z"
    }
  ],
  "offers": [
    {
      "id": "off_456",
      "short_id": "P001",
      "name": "Black Friday",
      "is_active": true,
      "external_id": "LMS_CODE",
      "product_id": "prd_789",
      "product_name": "Curso X",
      "profiles": 1,
      "plan_type": "yearly",
      "available_from": "2026-10-01T03:00:00.000Z",
      "available_until": "2026-10-31T02:59:59.000Z",
      "urgency_time_threshold_minutes": 60,
      "created_at": "2025-11-24T14:03:22Z",
      "updated_at": "2025-11-24T14:03:22Z"
    }
  ],
  "metadata": {}
}

Voucher atualizado (VOUCHER_UPDATED)

{
  "event_type": "voucher_updated",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2025-11-24T14:03:22Z",
  "origin": "mercury",
  "voucher": {
    "id": "vch_123",
    "type": "percentage",
    "code": "WELCOME10",
    "value": 15,
    "startAt": "2025-11-24T14:03:22Z",
    "endAt": null,
    "created_at": "2025-11-24T14:03:22Z",
    "updated_at": "2025-11-24T14:03:22Z"
  },
  "products": [
    {
      "id": "prd_789",
      "name": "Curso X",
      "code": "curso-x",
      "is_active": true,
      "checkoutGTM": null,
      "type": "course",
      "logoUrl": null,
      "sales_limit": 50,
      "created_at": "2025-11-24T14:03:22Z",
      "updated_at": "2025-11-24T14:03:22Z"
    }
  ],
  "offers": [
    {
      "id": "off_456",
      "short_id": "P001",
      "name": "Black Friday",
      "is_active": true,
      "external_id": "LMS_CODE",
      "product_id": "prd_789",
      "product_name": "Curso X",
      "profiles": 1,
      "plan_type": "yearly",
      "available_from": "2026-10-01T03:00:00.000Z",
      "available_until": "2026-10-31T02:59:59.000Z",
      "urgency_time_threshold_minutes": 60,
      "created_at": "2025-11-24T14:03:22Z",
      "updated_at": "2025-11-24T14:03:22Z"
    }
  ],
  "metadata": {}
}

Venda aprovada (SALE_CREATED)

{
  "event_type": "sale_created",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2023-10-01T10:30:00Z",
  "origin": "mercury",
  
  "contact": {
    "id": "cntct_123",
    "name": "Fulano",
    "email": "fulano@email.com",
    "phone": "+5527999999999",
    "cpf": "",
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z",
    "address": {
      "street": "Rua Exemplo",
      "number": "123",
      "complement": "Apto 45",
      "district": "Centro",
      "city": "Sao Paulo",
      "state": "SP",
      "postal_code": "01000-000",
      "country": "BR"
    }
  },
  "offer": {
    "id": "off_456",
    "short_id": "P001",
    "name": "Black Friday",
    "is_active": true,
    "external_id": "LMS_CODE",
    "product_id": "prd_789",
    "product_name": "Curso X",
    "profiles": 1,
    "plan_type": "yearly",
    "available_from": "2026-10-01T03:00:00.000Z",
    "available_until": "2026-10-31T02:59:59.000Z",
    "urgency_time_threshold_minutes": 60,
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z"
  },
  "product": {
    "id": "prd_789",
    "name": "Curso X",
    "code": "curso-x",
    "is_active": true,
    "checkoutGTM": null,
    "type": "course",
    "logoUrl": null,
    "sales_limit": 50,
    "sold_count": 50,
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z"
  },
  "tracking_parameters": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "utm_id": null,
    "utm_source_platform": null,
    "utm_marketing_tactic": null,
    "utm_creative_format": null,
    "ga_client_id": null,
    "gclid": null
  },
  "metadata": {
    "client_data": {
        "ipv4": "200.160.81.145"
    }
  },
  "sale": {
    "id": "sale_123456789",
    "approved_at": "2023-10-01T10:30:00Z",
    "canceled_at": null,
    "cycle": 1,
    "is_test": false,
    "amount_total": 199.99,
    "comission": 179.50,
    "iva": 2.30,
    "document":"",
    "document_type":"",
    "voucher_code": null,
    "created_at": "2023-10-01T10:30:00Z",
    "smart_installments": 3,
    "agreed_to_renew_at_checkout": true
  },
  "subscription": {
    "id": "sub_987654321",
    "period_start": "2023-10-01T10:30:00Z",
    "period_end": "2023-10-01T10:30:00Z",
    "payment_profile_id": "payment_id",
    "canceled_at": null,
    "cancel_at_period_end": null,
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z"
  },
  "payment_details": [
    {
      "amount": 113.07,
      "payment_method": "credit-card",
      "card_brand": "visa",
      "card_last_digits":"6411",
      "card_first_digits":"553527",
      "card_exp_month": 12,
      "card_exp_year": 2025,
      "installments": 1,
      "pix_tid": null,
      "bank_slip_link": null,
      "bank_slip_due_date": null,
      "nupay_cpf": null,
      "tid": "",
      "payment_profile_id": "payment_id",
      "mercury_fee": 11.17,
      "interest": 11.17,
      "discount": 11.17,
      "comission": 11.17,
      "paid_at": "2023-10-01T10:30:00Z",
      "created_at":"2023-10-01T10:30:00Z"
    }
  ]
}

Venda Cancelada (SALE_CANCELED)

{
  "event_type": "sale_canceled",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2023-10-01T10:30:00Z",
  "origin": "mercury",
  
  "contact": {
    "id": "cntct_123",
    "name": "Fulano",
    "email": "fulano@email.com",
    "phone": "+5527999999999",
    "cpf": "",
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z"
  },
  "offer": {
    "id": "off_456",
    "short_id": "P001",
    "name": "Black Friday",
    "is_active": true,
    "external_id": "LMS_CODE",
    "product_id": "prd_789",
    "product_name": "Curso X",
    "profiles": 1,
    "plan_type": "yearly",
    "available_from": "2026-10-01T03:00:00.000Z",
    "available_until": "2026-10-31T02:59:59.000Z",
    "urgency_time_threshold_minutes": 60,
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z"
  },
  "tracking_parameters": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "utm_id": null,
    "utm_source_platform": null,
    "utm_marketing_tactic": null,
    "utm_creative_format": null,
    "ga_client_id": null,
    "gclid": null
  },
  "metadata": {},
  "sale": {
    "id": "sale_123456789",
    "approved_at": "2023-10-01T10:30:00Z",
    "canceled_at": "2023-10-05T10:30:00Z",
    "cycle": 1,
    "is_test": false,
    "amount_total": 199.99,
    "comission": 179.50,
    "iva": 2.30,
    "document":"",
    "document_type":"",
    "voucher_code": null,
    "created_at": "2023-10-01T10:30:00Z",
    "smart_installments": 3,
    "agreed_to_renew_at_checkout": true
  },
  "subscription": {
    "id": "sub_987654321",
    "period_start": "2023-10-01T10:30:00Z",
    "period_end": "2023-10-01T10:30:00Z",
    "payment_profile_id": "payment_id",
    "canceled_at": null,
    "cancel_at_period_end": null,
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z"
  },
  "payment_details": [
    {
      "amount": 113.07,
      "payment_method": "credit-card",
      "card_brand": "visa",
      "card_last_digits":"6411",
      "card_first_digits":"553527",
      "card_exp_month": 12,
      "card_exp_year": 2025,
      "installments": 1,
      "pix_tid": null,
      "bank_slip_link": null,
      "bank_slip_due_date": null,
      "nupay_cpf": null,
      "tid": "",
      "payment_profile_id": "payment_id",
      "mercury_fee": 11.17,
      "interest": 11.17,
      "discount": 11.17,
      "comission": 11.17,
      "paid_at": "2023-10-01T10:30:00Z",
      "created_at":"2023-10-01T10:30:00Z"
    }
  ]
}

Venda recusada (ORDER_DECLINED)

{
  "event_type": "order_declined",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2023-10-01T10:30:00Z",
  "origin": "mercury",

  "lead": {
    "id": "ld_123",
    "name": "Sergio",
    "email": "sergio.lima.23123@gmail.com",
    "phone": "+5527999999999",
    "voucher_code": "WELCOME10",
    "created_at": "2025-11-24T14:03:22Z"
  },

  "offer": {
    "id": "off_456",
    "short_id": "P001",
    "name": "Black Friday",
    "is_active": true,
    "external_id": "LMS_CODE",
    "product_id": "prd_789",
    "product_name": "Curso X",
    "profiles": 1,
    "plan_type": "yearly",
    "available_from": "2026-10-01T03:00:00.000Z",
    "available_until": "2026-10-31T02:59:59.000Z",
    "urgency_time_threshold_minutes": 60,
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z"
  },

  "tracking_parameters": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "utm_id": null,
    "utm_source_platform": null,
    "utm_marketing_tactic": null,
    "utm_creative_format": null,
    "ga_client_id": null,
    "gclid": null
  },

  "metadata": {
    "client_data": {
        "ipv4": "200.160.81.125",
        "ipv6": "2804:7f0:b182:9a8f:40e1:cb7d:bd1:cf13",
        "device": {
            "os": {
                "name": "Mac OS",
                "version": "10.15.7"
            },
            "type": "browser",
            "browser": {
                "name": "Chrome",
                "version": "143"
            }
        },
        "timestamp": "1767992078374",
        "trueClientIp": "2804:7f0:b182:9a8f:40e1:cb7d:bd1:cf13"
    }
  },

  "payment_details": [
    {
      "amount": 113.07,
      "payment_method": "credit-card",
      "card_brand": "visa",
      "card_last_digits": "6411",
      "card_first_digits": "553527",
      "card_exp_month": 12,
      "card_exp_year": 2025,
      "installments": 1,
      "pix_tid": null,
      "bank_slip_link": null,
      "bank_slip_due_date": null,
      "nupay_cpf": null,
      "tid": "tid_123",
      "payment_profile_id": "payment_id",
      "mercury_fee": 0,
      "interest": 0,
      "discount": null,
      "comission": 113.07,
      "paid_at": null,
      "declined_reason": "Saldo insuficiente",
      "declined_code": "INSUFFICIENT_FUNDS",
      "created_at": "2023-10-01T10:30:00Z"
    }
  ]
}

Assinatura atualizada (SUBSCRIPTION_UPDATED)

{
  "event_type": "subscription_updated",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2025-11-24T14:03:22Z",
  "origin": "mercury",
  "sale": {
    "id": "sale_123456789",
    "approved_at": "2023-10-01T10:30:00Z",
    "cycle": 1,
    "is_test": false,
    "amount_total": 199.99,
    "comission": 179.50,
    "iva": 2.30,
    "document": "",
    "document_type": "",
    "voucher_code": null,
    "created_at": "2023-10-01T10:30:00Z",
    "smart_installments": 3,
    "agreed_to_renew_at_checkout": true
  },
  "subscription": {
    "id": "sub_987654321",
    "period_start": "2023-10-01T00:00:00.000Z",
    "period_end": "2023-11-01T00:00:00.000Z",
    "payment_profile_id": "payment_id",
    "class_start": "2023-11-01T00:00:00.000Z",
    "cancel_at_period_end": null,
    "created_at": "2023-10-01T00:00:00.000Z",
    "updated_at": "2023-11-01T00:00:00.000Z"
  },
  "offer": {
    "id": "off_456",
    "short_id": "P001",
    "name": "Black Friday",
    "is_active": true,
    "external_id": "LMS_CODE",
    "product_id": "prd_789",
    "product_name": "Curso X",
    "profiles": 1,
    "plan_type": "yearly",
    "available_from": "2026-10-01T03:00:00.000Z",
    "available_until": "2026-10-31T02:59:59.000Z",
    "urgency_time_threshold_minutes": 60,
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z"
  },
  "contact": {
    "id": "cntct_123",
    "name": "Fulano",
    "email": "fulano@email.com",
    "phone": "+5527999999999",
    "cpf": "",
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z",
    "address": {
      "street": "Rua Exemplo",
      "number": "123",
      "complement": "Apto 45",
      "district": "Centro",
      "city": "Sao Paulo",
      "state": "SP",
      "postal_code": "01000-000",
      "country": "BR"
    }
  }
}

O campo contact.address é opcional. Ele só é enviado quando houver pelo menos um campo estrutural de endereço preenchido, como rua, número, complemento, bairro, cidade, estado ou CEP. Se apenas country existir, a propriedade continua omitida do payload.

Assinatura cancelada (SUBSCRIPTION_CANCELED)

{
  "event_type": "subscription_canceled",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2025-11-24T14:03:22Z",
  "origin": "mercury",
  "sale": {
    "id": "sale_123456789",
    "approved_at": "2023-10-01T10:30:00Z",
    "cycle": 1,
    "is_test": false,
    "amount_total": 199.99,
    "comission": 179.50,
    "iva": 2.30,
    "document":"",
    "document_type":"",
    "voucher_code": null,
    "created_at": "2023-10-01T10:30:00Z",
    "smart_installments": 3,
    "agreed_to_renew_at_checkout": true
  },
  "subscription": {
    "id": "sub_987654321",
    "period_start": "2023-10-01T00:00:00.000Z",
    "period_end": "2023-11-01T00:00:00.000Z",
    "payment_profile_id": "payment_id",
    "class_start": "2023-11-01T00:00:00.000Z",
    "canceled_at": "2023-11-01T00:00:00.000Z",
    "cancel_at_period_end": null,
    "created_at": "2023-10-01T00:00:00.000Z",
    "updated_at": "2023-11-01T00:00:00.000Z",
    "cancellation_reason": "Solicitação do cliente"
  },
  "offer": {
    "id": "off_456",
    "short_id": "P001",
    "name": "Black Friday",
    "is_active": true,
    "external_id": "LMS_CODE",
    "product_id": "prd_789",
    "product_name": "Curso X",
    "profiles": 1,
    "plan_type": "yearly",
    "available_from": "2026-10-01T03:00:00.000Z",
    "available_until": "2026-10-31T02:59:59.000Z",
    "urgency_time_threshold_minutes": 60,
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z"
  },
  "contact": {
    "id": "cntct_123",
    "name": "Fulano",
    "email": "fulano@email.com",
    "phone": "+5527999999999",
    "cpf": "",
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z",
    "address": {
      "street": "Rua Exemplo",
      "number": "123",
      "complement": "Apto 45",
      "district": "Centro",
      "city": "Sao Paulo",
      "state": "SP",
      "postal_code": "01000-000",
      "country": "BR"
    }
  }
}

O campo contact.address e opcional. Ele so e enviado quando houver pelo menos um campo estrutural de endereco preenchido, como rua, numero, complemento, bairro, cidade, estado ou CEP. Se apenas country existir, a propriedade continua omitida do payload.

Fatura paga (INVOICE_PAID)

Enviado a cada fatura com pagamento confirmado: primeira parcela, parcelas seguintes de uma assinatura, renovação, fatura de negociação e baixa manual com cheque. Um pedido que paga várias faturas de uma vez gera um INVOICE_PAID por fatura.

INVOICE_PAID complementa o SALE_CREATED, sem substituí-lo: quando o pagamento da fatura também aprova uma venda nova, os dois eventos são enviados, sem garantia de ordem entre eles. Na negociação, o evento sai só para a fatura de negociação paga; as faturas que ela substitui são canceladas e não geram INVOICE_PAID.

{
  "event_type": "invoice_paid",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2025-11-24T14:03:22Z",
  "origin": "mercury",
  "contact": {
    "id": "cntct_123",
    "name": "Fulano",
    "email": "fulano@email.com",
    "phone": "+5527999999999",
    "cpf": "",
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z",
    "address": {
      "street": "Rua Exemplo",
      "number": "123",
      "complement": "Apto 45",
      "district": "Centro",
      "city": "Sao Paulo",
      "state": "SP",
      "postal_code": "01000-000",
      "country": "BR"
    }
  },
  "offer": {
    "id": "off_456",
    "short_id": "P001",
    "name": "Plano Anual",
    "is_active": true,
    "price": 1200,
    "external_id": "LMS_CODE",
    "product_id": "prd_789",
    "product_name": "Curso X",
    "product_code": "curso-x",
    "profiles": 1,
    "plan_type": "yearly",
    "available_from": "2026-10-01T03:00:00.000Z",
    "available_until": "2026-10-31T02:59:59.000Z",
    "urgency_time_threshold_minutes": 60,
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z"
  },
  "invoice": {
    "id": "invoiceId",
    "subscription_id": "subscriptionId",
    "sale_id": "saleId",
    "type": "renew",
    "cycle": 2,
    "amount": 100,
    "refunded_amount": null,
    "discount_amount": 0,
    "original_amount": 100,
    "iva": 0,
    "paid_at": "2025-11-24T14:03:20Z",
    "due_date": "2025-11-24T00:00:00Z",
    "refunded_at": null,
    "gateway_id": "gatewayId",
    "tid": "tid_123",
    "payment_method": "credit-card",
    "metadata": {}
  }
}

contact e offer têm o mesmo formato do SALE_CREATED. offer é o plano da fatura (ou, na falta dele, o plano da assinatura).

invoice.type indica a origem da fatura: sale, renew, upgrade, negotiation ou PRP; chega null quando a fatura não tem tipo. invoice.cycle é o número da parcela na assinatura.

invoice.metadata é a metadata da fatura, sem schema fixo.

Em baixa manual com cheque, invoice.payment_method chega como cheque.

Entrega pelo menos uma vez: a mesma fatura pode gerar mais de um INVOICE_PAID (por exemplo, quando o pagamento é reprocessado), cada um com seu próprio event_id. Para não registrar o mesmo pagamento duas vezes, deduplique por invoice.id, e não apenas por event_id.

Reembolso (INVOICE_REFUNDED)


{
  "event_type": "invoice_refunded",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2025-11-24T14:03:22Z",
  "origin": "mercury",
  "invoice": {
    "id": "invoiceId",
    "subscription_id": "subscriptionId",
    "sale_id": "saleId",
    "type": "sale",
    "cycle": 1,
    "amount": 90,
    "refunded_amount": 90,
    "discount_amount": 10,
    "original_amount": 100,
    "iva": 0,
    "paid_at": "",
    "due_date": "",
    "refunded_at": "",
    "gateway_id": "",
    "tid": "",
    "payment_method": "",
    "metadata": {}
  }
}

Contato atualizado (CONTACT_UPDATED)


{
  "event_type": "contact_updated",
  "event_id": "evt_01JDK9Q2Y7R4T9Z8K3M1",
  "occurred_at": "2025-11-24T14:03:22Z",
  "origin": "mercury",
  "contact": {
    "id": "cntct_123",
    "name": "Fulano",
    "email": "fulano@email.com",
    "phone": "+5527999999999",
    "cpf": "",
    "created_at": "2023-10-01T10:30:00Z",
    "updated_at": "2023-10-01T10:30:00Z",
    "address": {
      "street": "Rua Exemplo",
      "number": "123",
      "complement": "Apto 45",
      "district": "Centro",
      "city": "Sao Paulo",
      "state": "SP",
      "postal_code": "01000-000",
      "country": "BR"
    }
  },
  "metadata": {}
}

Resposta esperada do endpoint

Para que o webhook seja considerado entregue com sucesso, o endpoint deve retornar um status HTTP 2xx (ex: 200 ou 204).

Qualquer resposta fora desse intervalo será tratada como falha e acionará novas tentativas de envio.

Recomendamos que o endpoint responda o mais rápido possível e realize processamentos mais pesados de forma assíncrona.

Acompanhamento dos eventos

Na listagem de eventos, é possível acompanhar as principais informações de cada webhook, como data do evento, data da última execução, tipo de evento e status.

Lista de possíveis status:

Aguardando envio: amarelo

Enviado com sucesso: verde

Envio com erro: vermelho

Falhou: vermelho

Ao acessar os logs de um evento, ficam disponíveis detalhes completos do envio, incluindo produto, data do evento, última execução, URL de destino, tipo do evento, status, quantidade de tentativas, além da requisição enviada e da resposta recebida.

Também é possível reenviar manualmente um webhook pela interface.

Tentativas e reenvios (retry)

O envio aguarda a resposta do seu endpoint por até 10 segundos; se não houver resposta nesse prazo, a tentativa é tratada como falha e entra no fluxo de reenvio abaixo. Seu endpoint deve responder rapidamente (idealmente enfileirando o processamento do evento e retornando 2xx de imediato) para não esbarrar nesse limite.

Caso o endpoint retorne uma resposta diferente de 2xx, o webhook será reenviado automaticamente.

Exceção: Não são realizadas novas tentativas quando o endpoint retorna um dos seguintes códigos HTTP, pois indicam erro definitivo ou requisição inválida:

0, 401, 403, 404, 406, 410, 422, 505, 506, 510, 511

Ao todo, são realizadas 10 tentativas de envio, sendo 1 tentativa inicial e 9 novas tentativas em caso de falha, com intervalos progressivos conforme abaixo:

1ª nova tentativa: após 5 minutos

2ª nova tentativa: após 10 minutos

3ª nova tentativa: após 20 minutos

4ª nova tentativa: após 40 minutos

5ª nova tentativa: após 80 minutos

6ª nova tentativa: após 160 minutos

7ª nova tentativa: após 320 minutos

8ª nova tentativa: após 400 minutos

9ª nova tentativa: após 400 minutos

Idempotência

Cada evento possui um identificador único (event_id).
Recomendamos armazenar esse valor após o processamento para evitar executar o mesmo evento mais de uma vez em casos de reenvio.

Caso um webhook seja recebido com um event_id já processado, ele pode ser ignorado com segurança.

Checklist de integração

Antes de ir para produção, verifique se:

O endpoint aceita requisições POST

O endpoint retorna HTTP 2xx em caso de sucesso

O token de autenticação está sendo validado

O event_id está sendo usado para evitar duplicidade

Os logs estão sendo monitorados

O botão Testar webhook foi utilizado com sucesso

Eventos disponíveis#

Eventos disponíveis#

Configuração do Webhook#

Segurança#

Estrutura do payload#

Período de venda da oferta#

Limite de vendas do produto#

Campos monetários#

Métodos de pagamento#

Carteira digital#

Lead criado (LEAD_CREATED)#

Produto criado (PRODUCT_CREATED)#

Produto atualizado (PRODUCT_UPDATED)#

Oferta criada (OFFER_CREATED)#

Oferta atualizada (OFFER_UPDATED)#

Voucher criado (VOUCHER_CREATED)#

Voucher atualizado (VOUCHER_UPDATED)#

Venda aprovada (SALE_CREATED)#

Venda Cancelada (SALE_CANCELED)#

Venda recusada (ORDER_DECLINED)#

Assinatura atualizada (SUBSCRIPTION_UPDATED)#

Assinatura cancelada (SUBSCRIPTION_CANCELED)#

Fatura paga (INVOICE_PAID)#

Reembolso (INVOICE_REFUNDED)#

Contato atualizado (CONTACT_UPDATED)#

Resposta esperada do endpoint#

Acompanhamento dos eventos#

Tentativas e reenvios (retry)#

Idempotência#

Checklist de integração#

Eventos disponíveis

Eventos disponíveis

Configuração do Webhook

Segurança

Estrutura do payload

Período de venda da oferta

Limite de vendas do produto

Campos monetários

Métodos de pagamento

Carteira digital

Lead criado (LEAD_CREATED)

Produto criado (PRODUCT_CREATED)

Produto atualizado (PRODUCT_UPDATED)

Oferta criada (OFFER_CREATED)

Oferta atualizada (OFFER_UPDATED)

Voucher criado (VOUCHER_CREATED)

Voucher atualizado (VOUCHER_UPDATED)

Venda aprovada (SALE_CREATED)

Venda Cancelada (SALE_CANCELED)

Venda recusada (ORDER_DECLINED)

Assinatura atualizada (SUBSCRIPTION_UPDATED)

Assinatura cancelada (SUBSCRIPTION_CANCELED)

Fatura paga (INVOICE_PAID)

Reembolso (INVOICE_REFUNDED)

Contato atualizado (CONTACT_UPDATED)

Resposta esperada do endpoint

Acompanhamento dos eventos

Tentativas e reenvios (retry)

Idempotência

Checklist de integração