Webhooks HTTPS para ciclo de vida da subscrição SaaS

Em produtos Software / SaaS, a Zenofy envia POST JSON para o URL configurado no produto. Cada pedido inclui um «event» e campos para sincronizar acessos.

Indique o endpoint no formulário criar/editar produto (URL do webhook SaaS). Opcionalmente defina segredo enviado no cabeçalho X-Webhook-Secret, como na integração de webhooks por encomenda.

Os nomes são distintos do payload Integrações → Webhook: aqui usar subscription.created, subscription.activated, subscription.renewed, subscription.suspended, subscription.canceled e subscription.expired.

Utilize Content-Type: application/json; responda com HTTP 2xx rápido e processe offline se precisar. A entrega é «best-effort». Falhas podem ficar registadas para operadores — consulte registos em Zenofy quando necessário.

Datas e objeto order podem variar na serialização; trate payloads como evolutivos — novos campos podem aparecer.

Pedido HTTP

POST · Content-Type: application/json · optional X-Webhook-Secret

POST /your-endpoint HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Webhook-Secret: your-shared-secret

{ ... }

Eventos e valores de «event»

eventQuando (típico)
subscription.createdLinha de subscrição criada com a encomenda inicial
subscription.activatedPrimeiro pagamento concluído; período de acesso activo
subscription.renewedRenovação paga com sucesso; período prolongado (ver objeto renewal)
subscription.suspendedCalendário no produto: sem renovação após o fim do período, ao atingir os dias até suspender
subscription.canceledCancelamento manual pela app (comerciante) ou fluxos associados (subscription.canceled)
subscription.expiredPeríodo pago terminou sem renovação — já de imediato se não há calendário de suspensão/expiração passados após suspendida («dias até expirar»)

Forma do payload (campos)

  • event — um dos valores subscription.* acima
  • subscriptionId, productId, productName, merchantId
  • status — estado da subscrição (ex.: PENDING, ACTIVE, SUSPENDED, CANCELED, EXPIRED)
  • billingCycle — instantâneo do produto na criação (ex.: WEEKLY, MONTHLY, YEARLY)
  • currentPeriodStart, currentPeriodEnd — opcionais quando aplicável
  • customerEmail — normalizado/minúsculas para corresponder renovações
  • customerNameSnapshot
  • isRenewal — booleano; true em subscription.renewed
  • renewal — em renewed: renewalOrderId, previousPeriodEnd, newPeriodEnd (strings ISO 8601); senão habitualmente null
  • initialOrderId, lastPaidOrderId, pendingOrderId
  • orderId — identificador de contexto
  • order — quando incluído: status, totalAmount, currency, paidAt, customer (nome, email, tel.); pode ser null

Exemplos de corpo JSON

subscription.activated (ilustrativo)

{
  "event": "subscription.activated",
  "subscriptionId": "683a1b2c3d4e5f6789012345",
  "productId": "507f1f77bcf86cd799439011",
  "productName": "My SaaS plan",
  "merchantId": "merchantUserIdExample",
  "status": "ACTIVE",
  "billingCycle": "MONTHLY",
  "currentPeriodStart": "2026-05-01T10:00:00+02:00",
  "currentPeriodEnd": "2026-06-01T10:00:00+02:00",
  "customerEmail": "buyer@example.com",
  "customerNameSnapshot": "Ada Buyer",
  "isRenewal": false,
  "renewal": null,
  "initialOrderId": "673f92b2c3d94a0012abcd01",
  "lastPaidOrderId": "673f92b2c3d94a0012abcd01",
  "pendingOrderId": null,
  "orderId": "673f92b2c3d94a0012abcd01",
  "order": {
    "status": "PAID",
    "totalAmount": 99.99,
    "currency": "MZN",
    "paidAt": "2026-05-01T10:42:18+02:00",
    "customer": {
      "name": "Ada Buyer",
      "email": "buyer@example.com",
      "phoneNumber": "+258840000000"
    }
  }
}

subscription.renewed — atenção a renewal.previousPeriodEnd e renewal.newPeriodEnd

{
  "event": "subscription.renewed",
  "subscriptionId": "683a1b2c3d4e5f6789012345",
  "productId": "507f1f77bcf86cd799439011",
  "productName": "My SaaS plan",
  "merchantId": "merchantUserIdExample",
  "status": "ACTIVE",
  "billingCycle": "MONTHLY",
  "currentPeriodStart": "2026-05-01T10:00:00+02:00",
  "currentPeriodEnd": "2026-07-01T10:00:00+02:00",
  "customerEmail": "buyer@example.com",
  "customerNameSnapshot": "Ada Buyer",
  "isRenewal": true,
  "renewal": {
    "renewalOrderId": "673f92b2c3d94a0012abcd99",
    "previousPeriodEnd": "2026-06-01T10:00:00+02:00",
    "newPeriodEnd": "2026-07-01T10:00:00+02:00"
  },
  "initialOrderId": "673f92b2c3d94a0012abcd01",
  "lastPaidOrderId": "673f92b2c3d94a0012abcd99",
  "pendingOrderId": null,
  "orderId": "673f92b2c3d94a0012abcd99",
  "order": {
    "status": "PAID",
    "totalAmount": 99.99,
    "currency": "MZN",
    "paidAt": "2026-06-05T14:20:00+02:00",
    "customer": {
      "name": "Ada Buyer",
      "email": "buyer@example.com",
      "phoneNumber": "+258840000000"
    }
  }
}

Visão do comerciante — configuração, renovações e Catálogo → Assinaturas SaaS

Todos os tutoriais