Webhooks

A Malga utiliza o serviço de webhooks para notificar o seu sistema sobre os eventos ocorridos no motor de assinaturas. Através de webhooks, você consegue atualizar seu sistema sempre que um evento importante acontece, como a criação de uma assinatura, mudança de status ou criação de cobranças automáticas.

Fluxo básico para receber notificações via webhooks

Crie um serviço com um endpoint acessível dentro do seu sistema para receber as requisições de notificação dos eventos de assinatura.
Registre seu endpoint na Malga criando um webhook para receber notificações dos eventos desejados.
A Malga enviará uma requisição HTTP para seu endpoint com os dados do objeto alterado sempre que o determinado evento registrado no seu webhook acontecer.

Criação de um webhook

Realize a criação e gestão de webhooks usando o Serviço de Webhooks.

curl --location --request POST 'https://api.malga.io/v1/webhooks' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_SECRET_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "event": "subscription.created",
        "endpoint": "https://seu-dominio.com/webhooks/recurrence",
        "version": 1.1,
        "status": true
    }'

{
  "id": "31c142ad-4c30-4964-ba24-2df0f2bbb745",
  "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00",
  "event": "subscription.created",
  "endpoint": "https://seu-dominio.com/webhooks/recurrence",
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAIda0HljovhG1yKez/Du7MUoKup/cbXqPgwyGOATOiJQ=\n-----END PUBLIC KEY-----\n",
  "version": 1.1,
  "status": true,
  "createdAt": "2021-07-06T21:03:36.590Z",
  "updatedAt": "2021-07-06T21:03:36.590Z"
}

Evento de notificação enviado

Quando um determinado evento ocorre no motor de assinaturas, a Malga cria um objeto do tipo event que é enviado através de uma requisição HTTP para o seu endpoint cadastrado. O evento é imutável dentro da estrutura de notificações da Malga, isso significa que os dados do objeto que sofreu alteração são gravados junto com o evento, representando o estado do objeto imediatamente após o evento que o alterou. Exemplo de requisição de notificação de evento de uma assinatura enviada pela Malga para seu endpoint:

> POST <ENDPOINT_URL> HTTP/2
> Host: <ENDPOINT_HOST>
> User-Agent: axios/0.21.1
> Accept: application/json, text/plain, */*
> Content-Type: application/json
> X-Idempotency-Key: 5616b19e-4d99-4bd3-b415-4990e5cab4f4
> X-Plug-Date: 1660053072711
> X-Plug-Signature: 1f40fc92da241694750979ee6cf582f2d5d7d28e18335de05abc54d0560e0f5302860c652bf08d560252aa5e74210546f369fbbbce8c12cfc7957b2652fe9a75
> HTTP/2

{
  "id": "019a362f-f69c-7789-b535-7051a0031bbe",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "created",
  "data": {
    "subscription": {
      "id": "019a362f-f69c-7789-b535-7051a0031bbe",
      "name": "Test Subscription for Events",
      "clientId": "e0d26950-541b-4b28-b4ec-a95fb61f1a0d",
      "merchantId": "3e452afd-4b0f-4d11-87bb-6ad3345709d7",
      "customerId": "a3994087-d867-4c30-8b07-fe0a2f3db77b",
      "referenceKey": "test-event-ref",
      "currency": "BRL",
      "items": [
      {
        "name": "Ingresso VIP Mensal",
        "description": "Acesso VIP premium a eventos mensais",
        "amount": 29900,
        "quantity": 1,
        "sku": "VIP-EVENT-001",
        "risk": "Low",
        "categoryId": "entertainment",
        "locality": "São Paulo",
        "date": "2025-12-01",
        "type": 1,
        "genre": "Shows e Eventos",
        "tickets": {
          "quantityTicketSale": 1,
          "convenienceFeeValue": 15.5,
          "quantityFull": 1,
          "batch": 1
        },
        "location": {
          "street": "Av. Paulista",
          "number": "1000",
          "complement": "Centro de Convenções",
          "zipCode": "01310-100",
          "city": "São Paulo",
          "state": "SP",
          "country": "Brasil",
          "district": "Bela Vista",
          "reference": "Próximo ao MASP"
        }
      }
      ],
      "recurrence": {
        "interval": "monthly",
        "startAt": "2025-10-30",
        "nextDueDate": "2025-11-30"
      },
      "paymentMethod": {
        "type": "credit",
        "card": {
          "cardId": "5e334112-6f22-4c31-8e24-2f89ff77e21c"
        }
      },
      "status": "created",
      "amount": 2500,
      "liveMode": false,
      "createdAt": "2025-10-30T17:35:04.348495Z",
      "updatedAt": "2025-10-30T17:35:04.348495Z"
    }
  },
  "createdAt": "2025-10-30T17:36:16.718Z"
}

Eventos suportados para notificação via webhooks

Evento	Descrição
subscription.created	Evento enviado quando uma nova assinatura é criada (exceto quando trial ativo)
subscription.trial_started	Evento enviado quando uma assinatura é criada com período de trial ativo
subscription.activated	Evento enviado quando uma assinatura tem sua primeira cobrança aprovada
subscription.updated	Evento enviado quando uma assinatura é atualizada (mudança de valor, produtos, etc.)
subscription.paused	Evento enviado quando uma assinatura é pausada
subscription.resumed	Evento enviado quando uma assinatura pausada é retomada
subscription.unpaid	Evento enviado quando uma assinatura fica em situação de não paga
subscription.expired	Evento enviado quando uma assinatura expira
subscription.canceled	Evento enviado quando uma assinatura é cancelada manualmente ou automaticamente pelo scheduler de cancelamentos agendados
subscription.cancelation_scheduled	Evento enviado quando um cancelamento é agendado ou a data de agendamento é atualizada
subscription.cancelation_scheduled_removed	Evento enviado quando um agendamento de cancelamento é removido
subscription.cycle_failed	Evento enviado quando uma fatura de cobrança falhar devido a inconsistência de dados

Exemplos de payloads

Estrutura padrão do payload

Todos os eventos de assinatura seguem a mesma estrutura base. A diferença está no campo event e nos dados específicos dentro de data.

{
  "id": "5616b19e-4d99-4bd3-b415-4990e5cab4f4",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "created",
  "createdAt": "2021-07-05T18:56:08.672Z",
  "data": {
    "subscription": {
      "id": "01985cf8-96df-7d37-b17c-a9985a1e78bb",
      "name": "Assinatura Premium com Eventos",
      "status": "created",
      "amount": 29900,
      "currency": "BRL",
      "createdAt": "2025-07-30T20:14:12.191866Z",
      "updatedAt": "2025-07-30T20:14:12.191866Z"
    }
  }
}

Evento subscription.trial_started

O evento subscription.trial_started inclui informações sobre a assinatura que iniciou o processo de trial:

{
  "id": "019a362f-f69d-70b7-bb30-a86b6e1cb687",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "trial_started",
  "data": {
    "subscription": {
      "id": "019a362f-f69d-70b7-bb30-a86b6e1cb687",
      "name": "Test Subscription for Events",
      "clientId": "15af5e05-c807-4f33-8d74-5c3e2aded5be",
      "merchantId": "bf9e5b23-8223-4445-b6b0-8af2ea6c02fe",
      "customerId": "c6b8d0a1-37e0-420f-aeb2-4ef0c2758e52",
      "referenceKey": "test-event-ref",
      "currency": "BRL",
      "items": [
        {
          "name": "Test Product",
          "description": "Test Description",
          "amount": 2500,
          "quantity": 1
        }
      ],
      "recurrence": {
        "interval": "monthly",
        "startAt": "2025-11-30"
      },
      "trial": { 
        "endDate": "2025-11-30"
      },
      "paymentMethod": {
        "type": "credit",
        "card": {
          "cardId": "f6c9e6b2-d164-461c-afb3-c8093270e2b1"
        }
      },
      "status": "trialing",
      "amount": 2500,
      "liveMode": false,
      "createdAt": "2025-10-30T17:35:04.349047Z",
      "updatedAt": "2025-10-30T17:35:04.349047Z"
    }
  },
  "createdAt": "2025-10-30T17:38:07.132Z"
}

Evento subscription.activated

O evento subscription.activated inclui informações adicionais sobre a primeira fatura que foi processada com sucesso e vai para o status active:

{
  "id": "019a353e-bae2-7e5f-96e3-c0eab8681652",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "activated",
  "data": {
    "subscription": {
      "id": "019a353e-bae2-7e5f-96e3-c0eab8681652",
      "name": "Assinatura Premium com Eventos",
      "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd",
      "merchantId": "225d39bc-1fbb-480a-90bd-f0caad05d2d0",
      "customerId": "2a8b64ce-904c-4256-b79a-49525808609c",
      "referenceKey": "SUB-PREMIUM-001",
      "currency": "BRL",
      "items": [
        {
          "name": "Ingresso VIP Mensal",
          "description": "Acesso VIP premium a eventos mensais",
          "amount": 29900,
          "quantity": 1,
          "sku": "VIP-EVENT-001",
          "risk": "Low",
          "categoryId": "entertainment",
          "locality": "São Paulo",
          "date": "2025-12-01",
          "type": 1,
          "genre": "Shows e Eventos",
          "tickets": {
            "quantityTicketSale": 1,
            "convenienceFeeValue": 15.5,
            "quantityFull": 1,
            "batch": 1
          },
          "location": {
            "street": "Av. Paulista",
            "number": "1000",
            "complement": "Centro de Convenções",
            "zipCode": "01310-100",
            "city": "São Paulo",
            "state": "SP",
            "country": "Brasil",
            "district": "Bela Vista",
            "reference": "Próximo ao MASP"
          }
        }
      ],
      "recurrence": {
        "interval": "monthly",
        "startAt": "2025-10-30",
        "nextDueDate": "2025-11-30"
      },
      "paymentMethod": {
        "type": "credit",
        "card": {
          "cardId": "ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5"
        },
        "installments": 1
      },
      "status": "active",
      "amount": 29900,
      "liveMode": false,
      "createdAt": "2025-10-30T13:11:34.882942Z",
      "updatedAt": "2025-10-30T13:11:35.921247966Z"
    },
    "cycle": {
      "id": "019a353e-bafa-774b-9664-8217b3d19da6",
      "customerId": "2a8b64ce-904c-4256-b79a-49525808609c",
      "merchantId": "225d39bc-1fbb-480a-90bd-f0caad05d2d0",
      "cycle": 1,
      "status": "authorized",
      "amount": 29900,
      "scheduledAt": "2025-10-30",
      "paymentHistory": [
        {
          "id": "d6738023-a45c-4d58-a303-456da757cca6",
          "createdAt": "2025-10-30T13:11:34.917233965Z",
          "executedAt": "2025-10-30T13:11:34.905674924Z",
          "chargeId": "fe703f43-8f77-4780-80d1-b1c4ad44db6c",
          "attemptNumber": 1,
          "paymentMethod": {
            "type": "credit",
            "card": {
              "cardId": "ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5"
            },
            "installments": 1
          },
          "error": null
        }
      ],
      "createdAt": "2025-10-30T13:11:34.906418Z"
    }
  },
  "createdAt": "2025-10-30T14:38:59.398Z"
}

Evento subscription.unpaid

O evento subscription.unpaid inclui informações adicionais com o histórico de cobranças da fatura que falhou na última tentativa e atualizou a assinatura para unpaid:

{
  "id": "a1ec4c84-8d10-4cb8-b390-f7ae1f204638",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "unpaid",
  "data": {
    "subscription": {
      "id": "a1ec4c84-8d10-4cb8-b390-f7ae1f204638",
      "name": "Premium Subscription",
      "clientId": "a2a780a7-1f53-4766-88f9-85facc7ef0a3",
      "merchantId": "ad2c70ac-e1a5-4921-a0a5-b264d8bb5045",
      "customerId": "8b4b0bbe-3cf1-4fd4-95b5-b2700321fdc3",
      "referenceKey": "premium-sub-ref",
      "currency": "BRL",
      "items": [
        {
          "name": "Premium Plan",
          "description": "Monthly subscription plan",
          "amount": 29900,
          "quantity": 1
        }
      ],
      "recurrence": {
        "interval": "monthly",
        "startAt": "2025-10-30",
        "nextDueDate": "2025-11-30"
      },
      "paymentMethod": {
        "type": "credit",
        "card": {
          "cardId": "dbacd004-124f-40e4-80f7-655122a08355"
        },
        "installments": 1
      },
      "status": "unpaid",
      "amount": 29900,
      "liveMode": false,
      "createdAt": "2025-10-30T18:05:30.401145Z",
      "updatedAt": "2025-10-30T18:05:30.401145Z"
    },
    "cycle": {
      "id": "fc532536-9862-40e5-9613-2df214ae9b36",
      "customerId": "8b4b0bbe-3cf1-4fd4-95b5-b2700321fdc3",
      "merchantId": "ad2c70ac-e1a5-4921-a0a5-b264d8bb5045",
      "cycle": 1,
      "status": "failed",
      "amount": 29900,
      "scheduledAt": "2025-10-31",
      "paymentHistory": [
        {
          "id": "db137d73-d1e8-4830-8d56-e8e793541cfb",
          "createdAt": "2025-10-30T18:05:30.401145Z",
          "executedAt": "2025-10-31T19:05:30.401145Z",
          "chargeId": null,
          "attemptNumber": 5,
          "paymentMethod": {
            "type": "credit",
            "card": {
              "cardId": "dbacd004-124f-40e4-80f7-655122a08355"
            },
            "installments": 1
          },
          "error": {
            "message": "All retry attempts exhausted"
          }
        }
      ],
      "createdAt": "2025-10-30T18:05:30.401145Z"
    }
  },
  "createdAt": "2025-10-30T18:07:00.288Z"
}

Evento subscription.expired

O evento subscription.expired avisa que a última fatura referente àquela assinatura já foi paga e ela foi para o status expired:

{
  "id": "ddb07491-4992-45d4-abac-bef72c6806a9",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "expired",
  "data": {
    "subscription": {
      "id": "ddb07491-4992-45d4-abac-bef72c6806a9",
      "name": "Premium Subscription",
      "clientId": "3398028c-382d-4ab5-bcf9-67c8588a00e6",
      "merchantId": "fd401e88-bdd3-4325-af08-27f06293f114",
      "customerId": "5fc705b1-1114-496a-af6f-a645161bbe9b",
      "referenceKey": "premium-sub-ref",
      "currency": "BRL",
      "items": [
        {
          "name": "Premium Plan",
          "description": "Monthly subscription plan",
          "amount": 29900,
          "quantity": 1
        }
      ],
      "recurrence": {
        "interval": "monthly",
        "startAt": "2025-10-30",
        "nextDueDate": "2025-11-30"
      },
      "paymentMethod": {
        "type": "credit",
        "card": {
          "cardId": "4b56baed-66e8-4972-bc63-cf2d85fddf2c"
        },
        "installments": 1
      },
      "status": "active",
      "amount": 29900,
      "liveMode": false,
      "createdAt": "2025-10-30T17:35:04.349231Z",
      "updatedAt": "2025-10-30T17:35:04.349231Z"
    },
    "cycle": {
      "id": "b4159786-1c9e-4ae7-b30c-0b4d138b4d48",
      "customerId": "5fc705b1-1114-496a-af6f-a645161bbe9b",
      "merchantId": "fd401e88-bdd3-4325-af08-27f06293f114",
      "cycle": 1,
      "status": "authorized",
      "amount": 29900,
      "scheduledAt": "2025-10-31",
      "paymentHistory": [
        {
          "id": "cd613dd4-1403-4ff1-ad00-9d35e0da8525",
          "createdAt": "2025-10-30T17:35:04.349231Z",
          "executedAt": "2025-10-31T18:35:04.349231Z",
          "chargeId": "1a9ab4ee-9ec5-4b36-a592-cc3d9933a1fa",
          "attemptNumber": 1,
          "paymentMethod": {
            "type": "credit",
            "card": {
              "cardId": "4b56baed-66e8-4972-bc63-cf2d85fddf2c"
            },
            "installments": 1
          },
          "error": null
        }
      ],
      "createdAt": "2025-10-30T17:35:04.349231Z"
    }
  },
  "createdAt": "2025-10-30T17:39:54.264Z"
}

Evento subscription.canceled

O evento subscription.canceled é recebido quando uma assinatura é cancelada. Isso pode ocorrer de duas formas:

Cancelamento manual: Via endpoint de cancelamento ou atualização da assinatura
Cancelamento agendado efetivado: Quando o scheduler processa um cancelamento agendado e a data efetiva chega

Quando o cancelamento vem de um agendamento, os campos cancelAtPeriodEnd e scheduledCancellationReason estarão presentes no payload (se scheduledCancellationReason foi fornecido durante o agendamento). Exemplo de cancelamento manual:

{
  "id": "019a362f-f69d-7461-9ad9-738cca7b896d",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "canceled",
  "data": {
    "subscription": {
      "id": "019a362f-f69d-7461-9ad9-738cca7b896d",
      "name": "Test Subscription for Events",
      "clientId": "db33d3a9-5092-47ed-9672-100dd2d36408",
      "merchantId": "f441fdec-230a-41e3-b954-c222398e052e",
      "customerId": "fb6730f8-f8c5-4e86-8cb3-65df5eee8150",
      "referenceKey": "test-event-ref",
      "currency": "BRL",
      "items": [
        {
          "name": "Test Product",
          "description": "Test Description",
          "amount": 2500,
          "quantity": 1
        }
      ],
      "recurrence": {
        "interval": "monthly",
        "startAt": "2025-10-30",
        "nextDueDate": "2025-11-30"
      },
      "paymentMethod": {
        "type": "credit",
        "card": {
          "cardId": "3d655e9d-a4f8-4534-bf10-ec4ace54439d"
        }
      },
      "status": "canceled",
      "amount": 2500,
      "liveMode": false,
      "createdAt": "2025-10-30T17:35:04.349287Z",
      "updatedAt": "2025-10-30T17:35:04.349287Z"
    }
  },
  "createdAt": "2025-10-30T17:40:50.786Z"
}

Exemplo de cancelamento agendado efetivado:

{
  "id": "019a362f-f69d-7461-9ad9-738cca7b896d",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "canceled",
  "data": {
    "subscription": {
      "id": "019a362f-f69d-7461-9ad9-738cca7b896d",
      "name": "Test Subscription for Events",
      "clientId": "db33d3a9-5092-47ed-9672-100dd2d36408",
      "merchantId": "f441fdec-230a-41e3-b954-c222398e052e",
      "customerId": "fb6730f8-f8c5-4e86-8cb3-65df5eee8150",
      "referenceKey": "test-event-ref",
      "currency": "BRL",
      "items": [
        {
          "name": "Test Product",
          "description": "Test Description",
          "amount": 2500,
          "quantity": 1
        }
      ],
      "recurrence": {
        "interval": "monthly",
        "startAt": "2025-10-30",
        "nextDueDate": "2025-11-30"
      },
      "paymentMethod": {
        "type": "credit",
        "card": {
          "cardId": "3d655e9d-a4f8-4534-bf10-ec4ace54439d"
        }
      },
      "cancelAtPeriodEnd": true,
      "scheduledCancellationReason": "Mudança de plano",
      "status": "canceled",
      "amount": 2500,
      "liveMode": false,
      "createdAt": "2025-10-30T17:35:04.349287Z",
      "updatedAt": "2025-10-30T17:40:50.786Z"
    }
  },
  "createdAt": "2025-10-30T17:40:50.786Z"
}

Evento subscription.cancelation_scheduled

O evento subscription.cancelation_scheduled é enviado quando:

Um cancelamento agendado é criado pela primeira vez
A data de cancelamento agendado (scheduledCancellationAt) é atualizada

{
  "id": "019a362f-f69d-7461-9ad9-738cca7b896d",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "cancelation_scheduled",
  "data": {
    "subscription": {
      "id": "019a362f-f69d-7461-9ad9-738cca7b896d",
      "name": "Test Subscription for Events",
      "clientId": "db33d3a9-5092-47ed-9672-100dd2d36408",
      "merchantId": "f441fdec-230a-41e3-b954-c222398e052e",
      "customerId": "fb6730f8-f8c5-4e86-8cb3-65df5eee8150",
      "referenceKey": "test-event-ref",
      "currency": "BRL",
      "items": [
        {
          "name": "Test Product",
          "description": "Test Description",
          "amount": 2500,
          "quantity": 1
        }
      ],
      "recurrence": {
        "interval": "monthly",
        "startAt": "2025-10-30",
        "nextDueDate": "2025-11-30"
      },
      "paymentMethod": {
        "type": "credit",
        "card": {
          "cardId": "3d655e9d-a4f8-4534-bf10-ec4ace54439d"
        }
      },
      "cancelAtPeriodEnd": true,
      "scheduledCancellationAt": "2025-12-31",
      "scheduledCancellationReason": "Teste concluído",
      "status": "active",
      "amount": 2500,
      "liveMode": false,
      "createdAt": "2025-10-30T17:35:04.349287Z",
      "updatedAt": "2025-10-30T17:40:45.123456Z"
    }
  },
  "createdAt": "2025-10-30T17:40:50.786Z"
}

Evento subscription.cancelation_scheduled_removed

O evento subscription.cancelation_scheduled_removed é enviado quando o agendamento de cancelamento é removido (por exemplo, quando cancelAtPeriodEnd é definido como false).

{
  "id": "019a362f-f69d-7461-9ad9-738cca7b896e",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "cancelation_scheduled_removed",
  "data": {
    "subscription": {
      "id": "019a362f-f69d-7461-9ad9-738cca7b896d",
      "name": "Test Subscription for Events",
      "clientId": "db33d3a9-5092-47ed-9672-100dd2d36408",
      "merchantId": "f441fdec-230a-41e3-b954-c222398e052e",
      "customerId": "fb6730f8-f8c5-4e86-8cb3-65df5eee8150",
      "referenceKey": "test-event-ref",
      "currency": "BRL",
      "items": [
        {
          "name": "Test Product",
          "description": "Test Description",
          "amount": 2500,
          "quantity": 1
        }
      ],
      "recurrence": {
        "interval": "monthly",
        "startAt": "2025-10-30",
        "nextDueDate": "2025-11-30"
      },
      "paymentMethod": {
        "type": "credit",
        "card": {
          "cardId": "3d655e9d-a4f8-4534-bf10-ec4ace54439d"
        }
      },
      "cancelAtPeriodEnd": false,
      "status": "active",
      "amount": 2500,
      "liveMode": false,
      "createdAt": "2025-10-30T17:35:04.349287Z",
      "updatedAt": "2025-10-30T17:45:30.654321Z"
    }
  },
  "createdAt": "2025-10-30T17:45:35.123Z"
}

Note que quando o agendamento é removido, os campos scheduledCancellationAt e scheduledCancellationReason não aparecem no payload (são removidos do objeto subscription).

Evento subscription.paused

O evento subscription.paused é recebido ao pausar uma assinatura:

{
  "id": "019a362f-f69d-7b04-adbc-12cb755d371e",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "paused",
  "data": {
    "subscription": {
      "id": "019a362f-f69d-7b04-adbc-12cb755d371e",
      "name": "Test Subscription for Events",
      "clientId": "9ae1968f-d520-4045-8f84-ca982556084a",
      "merchantId": "a2cf2027-7821-4c10-a102-dc9024de7b9a",
      "customerId": "def4804e-3fcb-443d-b34a-132402f74bbc",
      "referenceKey": "test-event-ref",
      "currency": "BRL",
      "items": [
        {
          "name": "Test Product",
          "description": "Test Description",
          "amount": 2500,
          "quantity": 1
        }
      ],
      "recurrence": {
        "interval": "monthly",
        "startAt": "2025-10-30",
        "nextDueDate": "2025-11-30"
      },
      "paymentMethod": {
        "type": "credit",
        "card": {
          "cardId": "8e3870d6-8c59-41c6-bfdb-7bd82cee64a4"
        }
      },
      "status": "paused",
      "amount": 2500,
      "liveMode": false,
      "createdAt": "2025-10-30T17:35:04.349722Z",
      "updatedAt": "2025-10-30T17:35:04.349722Z"
    }
  },
  "createdAt": "2025-10-30T17:42:19.017Z"
}

Evento subscription.resumed

O evento subscription.resumed é recebido ao retomar uma assinatura que estava pausada:

{
  "id": "019a362f-f69d-7dda-af2e-6f95dbca0513",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "resumed",
  "data": {
    "subscription": {
      "id": "019a362f-f69d-7dda-af2e-6f95dbca0513",
      "name": "Test Subscription for Events",
      "clientId": "e58a463e-1bdf-4583-b067-9a926841c442",
      "merchantId": "e96d4f07-77a4-4ee1-8223-a0fc0501745d",
      "customerId": "7e71982d-246b-4b7b-9cee-05007d88dcf5",
      "referenceKey": "test-event-ref",
      "currency": "BRL",
      "items": [
        {
          "name": "Test Product",
          "description": "Test Description",
          "amount": 2500,
          "quantity": 1
        }
      ],
      "recurrence": {
        "interval": "monthly",
        "startAt": "2025-10-30",
        "nextDueDate": "2025-11-30"
      },
      "paymentMethod": {
        "type": "credit",
        "card": {
          "cardId": "49bc7302-ca69-4f17-a235-8e40337e90cd"
        }
      },
      "status": "created",
      "amount": 2500,
      "liveMode": false,
      "createdAt": "2025-10-30T17:35:04.349908Z",
      "updatedAt": "2025-10-30T17:35:04.349908Z"
    }
  },
  "createdAt": "2025-10-30T17:43:36.043Z"
}

Evento subscription.updated

O evento subscription.updated é recebido ao atualizar dados de uma assinatura:

{
  "id": "019a362f-f69d-7f0f-a9fa-ef1979ebdd7f",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "updated",
  "data": {
    "subscription": {
      "id": "019a362f-f69d-7f0f-a9fa-ef1979ebdd7f",
      "name": "Test Subscription for Events",
      "clientId": "e4ca93ec-4d9e-42be-a80a-4702b0c9c0d4",
      "merchantId": "4ce78ca0-bd7b-4c5a-bd95-2fe356f8897d",
      "customerId": "ed5f23e5-0bdb-492f-9536-7e4475c76ae6",
      "referenceKey": "test-event-ref",
      "currency": "BRL",
      "items": [
        {
          "name": "Test Product",
          "description": "Test Description",
          "amount": 2500,
          "quantity": 1
        }
      ],
      "recurrence": {
        "interval": "monthly",
        "startAt": "2025-10-30",
        "nextDueDate": "2025-11-30"
      },
      "paymentMethod": {
        "type": "credit",
        "card": {
          "cardId": "3e7e4644-4622-4acb-a387-23a214a3e5d6"
        }
      },
      "status": "created",
      "amount": 2500,
      "liveMode": false,
      "createdAt": "2025-10-30T17:35:04.349987Z",
      "updatedAt": "2025-10-30T17:35:04.349987Z"
    }
  },
  "createdAt": "2025-10-30T17:44:48.148Z"
}

Evento subscription.cycle_failed

Este evento é enviado quando o processamento de uma nova fatura de cobrança falha devido a alguma inconsistência nos dados da assinatura. Um exemplo comum é quando o merchant vinculado à assinatura foi desativado.
Nesses casos, nenhuma transação é criada.

{
  "id": "webhook_event_id_example",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "cycle_failed",
  "data": {
    "subscription": {
      "id": "subscription_id_example",
      "name": "Assinatura Mensal Premium",
      "clientId": "YOUR_CLIENT_ID",
      "merchantId": "YOUR_MERCHANT_ID",
      "customerId": "YOUR_CUSTOMER_ID",
      "referenceKey": "SUB-PREMIUM-001",
      "currency": "BRL",
      "items": [
        {
          "name": "Plano Premium",
          "description": "Acesso completo à plataforma com todos os recursos",
          "amount": 9990,
          "quantity": 1,
          "sku": "PREMIUM-MONTHLY",
          "risk": "low",
          "categoryId": "CAT-DIGITAL-SERVICES",
          "locality": "São Paulo - SP",
          "date": "2024-01-15",
          "type": "service",
          "genre": "subscription"
        }
      ],
      "recurrence": {
        "interval": "monthly",
        "cycles": null,
        "startAt": "2024-01-15",
        "endAt": null,
        "nextDueDate": "2024-04-15"
      },
      "paymentMethod": {
        "type": "credit",
        "installments": 1,
        "card": {
          "cardId": "aa0e8400-e29b-41d4-a716-446655440000"
        }
      },
      "status": "active",
      "amount": 9990,
      "trial": null,
      "liveMode": true,
      "createdAt": "2024-01-15T08:00:00Z",
      "updatedAt": "2024-03-15T10:30:00Z",
      "lastCycle": {
        "id": "cycle_id_example",
        "customerId": "YOUR_CUSTOMER_ID",
        "merchantId": "YOUR_MERCHANT_ID",
        "cycle": 1,
        "attempts": 1,
        "status": "failed",
        "amount": 9990,
        "items": [
          {
            "name": "Plano Premium",
            "description": "Acesso completo à plataforma com todos os recursos",
            "amount": 9990,
            "quantity": 1,
            "sku": "PREMIUM-MONTHLY"
          }
        ],
        "isEmulated": false,
        "createdAt": "2024-03-10T00:00:00Z",
        "scheduledAt": "2024-03-15",
        "executedAt": "2024-03-15",
        "nextAttemptAt": ""
      }
    },
    "errorCode": 400
  },
  "createdAt": "2025-10-09T18:10:49.963Z"
}

Comportamento especial para startAt sendo hoje

Quando uma assinatura é criada com startAt definido como a data atual, o motor de assinaturas processa a primeira cobrança imediatamente.
Nesse caso, você deve receber webhooks na ordem abaixo:

Ordem de eventos quando startAt é hoje:

subscription.created - Assinatura criada
subscription.activated (se sucesso) ou subscription.cycle_failed (caso haja alguma inconsistência de dados na assinatura)
subscription.unpaid (se todas as tentativas de cobrança da fatura falharem)

Webhooks de Cobrança

Quando o motor de assinaturas cria cobranças automaticamente, você também receberá os webhooks de cobrança padrão da Malga. Nestes casos, o subscriptionId estará presente no payload da cobrança para identificar a qual assinatura a cobrança pertence.

Exemplo de webhook de cobrança com subscriptionId

{
  "id": "5616b19e-4d99-4bd3-b415-4990e5cab4f4",
  "apiVersion": "1.1",
  "object": "transaction",
  "event": "pending",
  "createdAt": "2021-07-05T18:56:08.672Z",
  "data": {
    "id": "chr_123456789",
    "amount": 29900,
    "currency": "BRL",
    "status": "pending",
    "customerId": "cus_123456789",
    "subscriptionId": "sub_123456789",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Esta documentação fornece uma base sólida para implementar webhooks de assinatura seguindo os padrões da Malga. Lembre-se de adaptar os exemplos para sua stack tecnológica específica e sempre testar em ambiente de desenvolvimento antes de ir para produção.

Comece na Malga

Conexões

Guias

Serviços adicionais

Fluxo básico para receber notificações via webhooks

Criação de um webhook

Evento de notificação enviado

Eventos suportados para notificação via webhooks

Exemplos de payloads

Estrutura padrão do payload

Evento subscription.trial_started

Evento subscription.activated

Evento subscription.unpaid

Evento subscription.expired

Evento subscription.canceled

Evento subscription.cancelation_scheduled

Evento subscription.cancelation_scheduled_removed

Evento subscription.paused

Evento subscription.resumed

Evento subscription.updated

Evento subscription.cycle_failed

Comportamento especial para startAt sendo hoje

Webhooks de Cobrança

Exemplo de webhook de cobrança com subscriptionId

​Fluxo básico para receber notificações via webhooks

​Criação de um webhook

​Evento de notificação enviado

​Eventos suportados para notificação via webhooks

​Exemplos de payloads

​Estrutura padrão do payload

​Evento subscription.trial_started

​Evento subscription.activated

​Evento subscription.unpaid

​Evento subscription.expired

​Evento subscription.canceled

​Evento subscription.cancelation_scheduled

​Evento subscription.cancelation_scheduled_removed

​Evento subscription.paused

​Evento subscription.resumed

​Evento subscription.updated

​Evento subscription.cycle_failed

​Comportamento especial para startAt sendo hoje

​Webhooks de Cobrança

​Exemplo de webhook de cobrança com subscriptionId

Fluxo básico para receber notificações via webhooks

Criação de um webhook

Evento de notificação enviado

Eventos suportados para notificação via webhooks

Exemplos de payloads

Estrutura padrão do payload

Evento subscription.trial_started

Evento subscription.activated

Evento subscription.unpaid

Evento subscription.expired

Evento subscription.canceled

Evento subscription.cancelation_scheduled

Evento subscription.cancelation_scheduled_removed

Evento subscription.paused

Evento subscription.resumed

Evento subscription.updated

Evento subscription.cycle_failed

Comportamento especial para startAt sendo hoje

Webhooks de Cobrança

Exemplo de webhook de cobrança com subscriptionId