Skip to main content
O ImperiumPay Gateway envia notificações automáticas via webhook quando ocorrem eventos importantes nas suas assinaturas.

​
Eventos de Assinatura

Os seguintes eventos geram notificações de webhook:
EventoDescriçãoQuando Ocorre
subscription.createdAssinatura criadaApós criação da transação com assinatura
subscription.activatedAssinatura ativadaPrimeiro pagamento confirmado
subscription.trial_startedTrial iniciadoAssinatura entra em período de trial
subscription.trial_endedTrial encerradoPeríodo de trial terminou
subscription.renewedAssinatura renovadaCobrança recorrente bem-sucedida
subscription.payment_failedFalha no pagamentoCobrança recorrente falhou
subscription.pausedAssinatura pausadaAssinatura foi pausada
subscription.resumedAssinatura reativadaAssinatura foi reativada
subscription.cancelledAssinatura canceladaAssinatura foi cancelada
subscription.expiredAssinatura expiradaPeríodo da assinatura encerrou

​
Configuração

Configure seu webhook no painel administrativo do ImperiumPay Gateway ou inclua o campo postbackUrl ao criar a transação com assinatura.
Nota: Se você configurar o postbackUrl na criação da transação, receberá notificações tanto da transação quanto da assinatura associada.

​
Formato da Notificação

​
Estrutura Base

Todas as notificações de assinatura seguem esta estrutura: 
{
  "event": "subscription.activated",
  "timestamp": "2026-02-24T15:35:00.000Z",
  "subscription": {
    "id": 123,
    "status": "ACTIVE",
    "billingCycle": "MONTHLY",
    "amount": 5000,
    "nextBillingDate": "2026-03-24T15:30:00.000Z",
    "trialEndsAt": null,
    "customerEmail": "joao.santos@example.com",
    "customerName": "João Silva Santos",
    "customerDocument": "12345678900",
    "customerPhone": "5511999999999",
    "paymentMethod": "PIX",
    "product": {
      "id": 456,
      "name": "Assinatura Premium Mensal"
    }
  },
  "sale": {
    "id": 4607,
    "amount": 5000,
    "status": "PAGO",
    "paymentMethod": "PIX"
  }
}

​
Campos

​
event
string
required
Tipo do evento. Valores possíveis: subscription.created, subscription.activated, subscription.trial_started, subscription.trial_ended, subscription.renewed, subscription.payment_failed, subscription.paused, subscription.resumed, subscription.cancelled, subscription.expired
​
timestamp
string
required
Data e hora do evento (ISO 8601)
​
subscription
object
required
Dados da assinatura
​
subscription.id
integer
required
ID único da assinatura
​
subscription.status
string
required
Status atual da assinatura
​
subscription.billingCycle
string
required
Ciclo de cobrança
​
subscription.amount
integer
required
Valor da assinatura em centavos
​
subscription.nextBillingDate
string
Data da próxima cobrança (ISO 8601)
​
subscription.trialEndsAt
string
Data de término do trial (ISO 8601). null se não houver trial.
​
subscription.customerEmail
string
required
Email do cliente
​
subscription.customerName
string
required
Nome do cliente
​
subscription.customerDocument
string
Documento do cliente (CPF/CNPJ)
​
subscription.customerPhone
string
Telefone do cliente
​
subscription.paymentMethod
string
required
Método de pagamento
​
subscription.product
object
Dados do produto associado
​
sale
object
Dados da transação associada (quando aplicável)

​
Exemplos por Evento

​
subscription.created

Enviado quando uma nova assinatura é criada (status PENDING): 
{
  "event": "subscription.created",
  "timestamp": "2026-02-24T15:30:00.000Z",
  "subscription": {
    "id": 123,
    "status": "PENDING",
    "billingCycle": "MONTHLY",
    "amount": 5000,
    "nextBillingDate": "2026-03-24T15:30:00.000Z",
    "trialEndsAt": null,
    "customerEmail": "joao.santos@example.com",
    "customerName": "João Silva Santos",
    "paymentMethod": "PIX",
    "product": {
      "id": 456,
      "name": "Assinatura Premium"
    }
  },
  "sale": {
    "id": 4607,
    "amount": 5000,
    "status": "PENDENTE",
    "paymentMethod": "PIX"
  }
}

​
subscription.activated

Enviado quando a assinatura é ativada após o primeiro pagamento: 
{
  "event": "subscription.activated",
  "timestamp": "2026-02-24T15:35:00.000Z",
  "subscription": {
    "id": 123,
    "status": "ACTIVE",
    "billingCycle": "MONTHLY",
    "amount": 5000,
    "nextBillingDate": "2026-03-24T15:30:00.000Z",
    "trialEndsAt": null,
    "startedAt": "2026-02-24T15:35:00.000Z",
    "customerEmail": "joao.santos@example.com",
    "customerName": "João Silva Santos",
    "paymentMethod": "PIX",
    "product": {
      "id": 456,
      "name": "Assinatura Premium"
    }
  },
  "sale": {
    "id": 4607,
    "amount": 5000,
    "status": "PAGO",
    "paymentMethod": "PIX"
  }
}

​
subscription.trial_started

Enviado quando a assinatura entra em período de trial: 
{
  "event": "subscription.trial_started",
  "timestamp": "2026-02-24T15:35:00.000Z",
  "subscription": {
    "id": 124,
    "status": "TRIALING",
    "billingCycle": "MONTHLY",
    "amount": 9900,
    "nextBillingDate": "2026-03-10T15:35:00.000Z",
    "trialEndsAt": "2026-03-03T15:35:00.000Z",
    "customerEmail": "maria@example.com",
    "customerName": "Maria Oliveira",
    "paymentMethod": "CREDIT_CARD",
    "product": {
      "id": 789,
      "name": "Plano Pro - 7 dias grátis"
    }
  }
}

​
subscription.trial_ended

Enviado quando o período de trial termina: 
{
  "event": "subscription.trial_ended",
  "timestamp": "2026-03-03T15:35:00.000Z",
  "subscription": {
    "id": 124,
    "status": "ACTIVE",
    "billingCycle": "MONTHLY",
    "amount": 9900,
    "nextBillingDate": "2026-04-03T15:35:00.000Z",
    "trialEndsAt": "2026-03-03T15:35:00.000Z",
    "customerEmail": "maria@example.com",
    "customerName": "Maria Oliveira",
    "paymentMethod": "CREDIT_CARD"
  },
  "sale": {
    "id": 4650,
    "amount": 9900,
    "status": "PAGO",
    "paymentMethod": "CREDIT_CARD"
  }
}

​
subscription.renewed

Enviado quando uma cobrança recorrente é bem-sucedida: 
{
  "event": "subscription.renewed",
  "timestamp": "2026-03-24T15:30:00.000Z",
  "subscription": {
    "id": 123,
    "status": "ACTIVE",
    "billingCycle": "MONTHLY",
    "amount": 5000,
    "nextBillingDate": "2026-04-24T15:30:00.000Z",
    "totalBillings": 2,
    "successfulBillings": 2,
    "customerEmail": "joao.santos@example.com",
    "customerName": "João Silva Santos",
    "paymentMethod": "PIX"
  },
  "sale": {
    "id": 4700,
    "amount": 5000,
    "status": "PAGO",
    "paymentMethod": "PIX"
  }
}

​
subscription.payment_failed

Enviado quando uma cobrança recorrente falha: 
{
  "event": "subscription.payment_failed",
  "timestamp": "2026-03-24T15:30:00.000Z",
  "subscription": {
    "id": 125,
    "status": "PAST_DUE",
    "billingCycle": "MONTHLY",
    "amount": 19900,
    "nextBillingDate": "2026-03-27T15:30:00.000Z",
    "totalBillings": 2,
    "successfulBillings": 1,
    "failedBillings": 1,
    "customerEmail": "carlos@example.com",
    "customerName": "Carlos Pereira",
    "paymentMethod": "CREDIT_CARD"
  },
  "failureReason": "Cartão recusado pelo banco emissor",
  "retryScheduled": true,
  "nextRetryDate": "2026-03-27T15:30:00.000Z"
}

​
subscription.paused

Enviado quando a assinatura é pausada: 
{
  "event": "subscription.paused",
  "timestamp": "2026-02-25T10:00:00.000Z",
  "subscription": {
    "id": 123,
    "status": "PAUSED",
    "billingCycle": "MONTHLY",
    "amount": 5000,
    "nextBillingDate": null,
    "pausedAt": "2026-02-25T10:00:00.000Z",
    "customerEmail": "joao.santos@example.com",
    "customerName": "João Silva Santos",
    "paymentMethod": "PIX"
  }
}

​
subscription.resumed

Enviado quando a assinatura é reativada: 
{
  "event": "subscription.resumed",
  "timestamp": "2026-03-01T10:00:00.000Z",
  "subscription": {
    "id": 123,
    "status": "ACTIVE",
    "billingCycle": "MONTHLY",
    "amount": 5000,
    "nextBillingDate": "2026-04-01T10:00:00.000Z",
    "resumedAt": "2026-03-01T10:00:00.000Z",
    "customerEmail": "joao.santos@example.com",
    "customerName": "João Silva Santos",
    "paymentMethod": "PIX"
  }
}

​
subscription.cancelled

Enviado quando a assinatura é cancelada: 
{
  "event": "subscription.cancelled",
  "timestamp": "2026-02-28T18:00:00.000Z",
  "subscription": {
    "id": 126,
    "status": "CANCELLED",
    "billingCycle": "MONTHLY",
    "amount": 5000,
    "nextBillingDate": null,
    "cancelledAt": "2026-02-28T18:00:00.000Z",
    "customerEmail": "ana@example.com",
    "customerName": "Ana Costa",
    "paymentMethod": "PIX"
  },
  "cancellationReason": "Solicitação do cliente"
}

​
subscription.expired

Enviado quando a assinatura expira: 
{
  "event": "subscription.expired",
  "timestamp": "2027-02-24T15:30:00.000Z",
  "subscription": {
    "id": 125,
    "status": "EXPIRED",
    "billingCycle": "YEARLY",
    "amount": 19900,
    "nextBillingDate": null,
    "expiredAt": "2027-02-24T15:30:00.000Z",
    "customerEmail": "carlos@example.com",
    "customerName": "Carlos Pereira",
    "paymentMethod": "CREDIT_CARD"
  }
}

​
Segurança

Importante: Webhooks de assinatura incluem assinatura HMAC-SHA256 no header X-Signature. Sempre valide a assinatura antes de processar a notificação.

​
Validação da Assinatura

const crypto = require('crypto');

function validateWebhookSignature(payload, signature, secretKey) {
  const hmac = crypto.createHmac('sha256', secretKey);
  hmac.update(JSON.stringify(payload));
  const expectedSignature = hmac.digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

app.post('/webhook/subscription', (req, res) => {
  const signature = req.headers['x-signature'];
  const payload = req.body;
  const secretKey = process.env.POSTBACK_SECRET_KEY;
  
  if (!validateWebhookSignature(payload, signature, secretKey)) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }
  
  // Processar evento
  const { event, subscription } = payload;
  
  switch (event) {
    case 'subscription.activated':
      // Liberar acesso ao produto
      break;
    case 'subscription.cancelled':
      // Revogar acesso ao produto
      break;
    case 'subscription.payment_failed':
      // Notificar cliente sobre falha
      break;
    // ... outros eventos
  }
  
  res.status(200).json({ success: true });
});

​
Boas Práticas

Retorne HTTP 200

Sempre retorne status 200 para indicar que recebeu a notificação

Valide a Assinatura

Sempre valide o header X-Signature antes de processar

Idempotência

Implemente lógica idempotente para evitar duplicação

Processamento Assíncrono

Processe webhooks de forma assíncrona para evitar timeouts
Dica: Armazene o subscription.id e event para implementar idempotência e evitar processar o mesmo evento duas vezes.

​
Retry Policy

Se o seu servidor não retornar HTTP 200, o ImperiumPay Gateway tentará reenviar a notificação:
TentativaIntervalo
1ªImediata
2ª5 minutos
3ª30 minutos
4ª2 horas
5ª24 horas
Após 5 tentativas sem sucesso, a notificação é marcada como falha e não será reenviada.