A Malga utiliza o serviço de webhooks para notificar o seu sistema sobre os eventos ocorridos no motor de recorrência. 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 recorrência.
  • 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
    }'

​
Evento de notificação enviado

Quando um determinado evento ocorre no motor de recorrência, 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": "5616b19e-4d99-4bd3-b415-4990e5cab4f4",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "created",
  "createdAt": "2021-07-05T18:56:08.672Z",
  "data": {
    "id": "01985cf8-96df-7d37-b17c-a9985a1e78bb",
    "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-07-30",
      "nextDueDate": "2025-07-30"
    },
    "paymentSource": {
      "sourceType": "card",
      "cardId": "ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5"
    },
    "status": "created",
    "amount": 29900,
    "liveMode": true,
    "createdAt": "2025-07-30T20:14:12.191866Z",
    "updatedAt": "2025-07-30T20:14:12.191866Z"
  }
}

​
Eventos suportados para notificação via webhooks

​
Eventos Subscription

EventoDescrição
subscription.createdEvento enviado quando uma nova assinatura é criada
subscription.activatedEvento enviado quando uma assinatura tem seu primeiro pagamento aprovado
subscription.updatedEvento enviado quando uma assinatura é atualizada (mudança de valor, produtos, etc.)
subscription.pausedEvento enviado quando uma assinatura é pausada
subscription.resumedEvento enviado quando uma assinatura pausada é retomada
subscription.unpaidEvento enviado quando uma assinatura fica em situação de não paga
subscription.expiredEvento enviado quando uma assinatura expira

​
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": {
    "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.activated

O evento subscription.activated inclui informações adicionais sobre o cycle que foi processado com sucesso: 
{
  "id": "5616b19e-4d99-4bd3-b415-4990e5cab4f4",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "activated",
  "createdAt": "2021-07-05T18:56:08.672Z",
  "data": {
    "id": "01985cf8-96df-7d37-b17c-a9985a1e78bb",
    "name": "Assinatura Premium com Eventos",
    "status": "active",
    "amount": 29900,
    "currency": "BRL",
    "createdAt": "2025-07-30T20:14:12.191866Z",
    "updatedAt": "2025-07-30T20:14:15.239441719Z",
    "cycle": {
      "id": "01985cf8-9877-7c09-bbf6-2cceb3384a61",
      "customerId": "2a8b64ce-904c-4256-b79a-49525808609c",
      "merchantId": "225d39bc-1fbb-480a-90bd-f0caad05d2d0",
      "cycle": 1,
      "status": "authorized",
      "createdAt": "2025-07-30T20:14:12.599715Z"
    }
  }
}

​
Webhooks de Cobrança

Quando o motor de recorrência 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 recorrência 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.