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_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.

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.

{
  "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",
    "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,
    "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,
    "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,
    "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",
    "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,
    "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",
    "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,
      "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",
      "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,
      "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",
      "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",
    "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",
    "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",
    "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",
    "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",
    "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.

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",
    "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#

Campos monetários#

Métodos de pagamento#

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)#

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

Campos monetários

Métodos de pagamento

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)

Reembolso (INVOICE_REFUNDED)

Contato atualizado (CONTACT_UPDATED)

Resposta esperada do endpoint

Acompanhamento dos eventos

Tentativas e reenvios (retry)

Idempotência

Checklist de integração