Webhooks HTTPS para eventos da encomenda

Indique o seu endpoint no produto para receber notificações servidor-a-servidor — o mesmo URL para todos os tipos de evento; o corpo JSON indica o que ocorreu.

Na app Zenofy, nas integrações do produto, escolha Webhook, indique um URL HTTPS (e um segredo opcional partilhado), ative a integração e guarde. Cada produto tem as suas definições de webhook.

É feito POST para o seu URL quando a encomenda é paga, reembolsada ou cancelada. O campo «event» é order_paid, order_refunded ou order_cancelled; «status» reflete a encomenda (PAID, REFUNDED ou CANCELLED).

Os pedidos usam Content-Type: application/json. Se configurou um segredo, enviamos também o cabeçalho X-Webhook-Secret com esse valor para poder validar o pedido.

Responda rapidamente com HTTP 2xx e processe o payload em segundo plano se necessário. A entrega é «best-effort»; consulte os logs do servidor e, na administração Zenofy, os registos de webhooks em caso de falha.

Pedido HTTP

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

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

{ ... }

Eventos e valores de «event»

event	Quando	Típico «status» no corpo
`order_paid`	A encomenda transitou para paga	`PAID`
`order_refunded`	A encomenda foi marcada como reembolsada	`REFUNDED`
`order_cancelled`	A encomenda foi marcada como cancelada	`CANCELLED`

Forma do payload (campos)

event — order_paid, order_refunded ou order_cancelled
orderId, status, totalAmount, currency
paymentGateway, paymentReference (opcional)
createdAt, paidAt (opcional até estar paga)
affiliateId (opcional)
customer: name, email, phoneNumber
items: linhas (productId, productName, quantity, unitPrice, totalPrice, currency, isBumpProduct)

Exemplos de corpo JSON

order_paid (resumido)

{
  "event": "order_paid",
  "orderId": "673f92b2c3d94a0012abcd01",
  "status": "PAID",
  "totalAmount": 149.99,
  "currency": "MZN",
  "paymentGateway": "EMIS_GPO",
  "paymentReference": "PC673F92_1A",
  "createdAt": "2026-05-01T10:30:00+02:00",
  "paidAt": "2026-05-01T10:42:18+02:00",
  "affiliateId": null,
  "customer": {
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "phoneNumber": "+258840000000"
  },
  "items": [
    {
      "productId": "507f1f77bcf86cd799439011",
      "productName": "Starter course",
      "quantity": 1,
      "unitPrice": 149.99,
      "totalPrice": 149.99,
      "currency": "MZN",
      "isBumpProduct": false
    }
  ]
}

order_refunded (resumido)

{
  "event": "order_refunded",
  "orderId": "673f92b2c3d94a0012abcd01",
  "status": "REFUNDED",
  "totalAmount": 149.99,
  "currency": "MZN",
  "paymentGateway": "EMIS_GPO",
  "paymentReference": "PC673F92_1A",
  "createdAt": "2026-05-01T10:30:00+02:00",
  "paidAt": "2026-05-01T10:42:18+02:00",
  "affiliateId": null,
  "customer": {
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "phoneNumber": "+258840000000"
  },
  "items": [
    {
      "productId": "507f1f77bcf86cd799439011",
      "productName": "Starter course",
      "quantity": 1,
      "unitPrice": 149.99,
      "totalPrice": 149.99,
      "currency": "MZN",
      "isBumpProduct": false
    }
  ]
}

order_cancelled (resumido)

{
  "event": "order_cancelled",
  "orderId": "673f92b2c3d94a0012abcd02",
  "status": "CANCELLED",
  "totalAmount": 49.00,
  "currency": "MZN",
  "paymentGateway": null,
  "paymentReference": null,
  "createdAt": "2026-05-01T09:15:22+02:00",
  "paidAt": null,
  "affiliateId": null,
  "customer": {
    "name": "Test Buyer",
    "email": "buyer@example.org",
    "phoneNumber": null
  },
  "items": [
    {
      "productId": "507f191e810c19729de860ea",
      "productName": "Digital guide",
      "quantity": 1,
      "unitPrice": 49.00,
      "totalPrice": 49.00,
      "currency": "MZN",
      "isBumpProduct": false
    }
  ]
}

Todos os tutoriais