Skip to main content
Os webhooks permitem que sua aplicação seja notificada quando algo acontecer no Upag (assinatura criada, pagamento aprovado, fatura paga, etc.). Configure uma URL no painel e selecione os eventos que deseja receber.

​
Envelope da requisição

Cada requisição de webhook enviada pelo Upag segue este formato: 
{
  "event": "subscription.created",
  "data": { }
}
  • event — Nome do evento (ex.: subscription.created, payment.approved). Use este valor para decidir como processar o payload.
  • data — Objeto com os dados do recurso. A estrutura de data depende do tipo de evento. Consulte as páginas de referência abaixo para cada payload.

​
Tipos de evento

​
Assinaturas (subscription)

EventoDescrição
subscription.createdNova assinatura criada
subscription.activeAssinatura ativa
subscription.canceledAssinatura cancelada
subscription.past_dueAssinatura em atraso
subscription.trialingAssinatura em período de trial
subscription.incompleteAssinatura incompleta
subscription.pausedAssinatura pausada
subscription.voidAssinatura anulada
Referência do objeto em data: Payload Subscription.

​
Pagamentos (payment)

EventoDescrição
payment.createdNovo pagamento criado
payment.incompletePagamento incompleto
payment.pendingPagamento pendente
payment.approvedPagamento aprovado
payment.refundedPagamento reembolsado
payment.refusedPagamento recusado
payment.failedPagamento falhou
Referência do objeto em data: Payload Payment.

​
Faturas (invoice)

EventoDescrição
invoice.createdNova fatura criada
invoice.openedFatura aberta
invoice.paidFatura paga
invoice.voidedFatura anulada
Referência do objeto em data: Payload Invoice.

​
Segurança

Para garantir que a requisição foi enviada pelo Upag, verifique a assinatura usando o cabeçalho da requisição (por exemplo x-Upag-signature ou o nome configurado no painel) e sua chave secreta de webhook. A assinatura é um HMAC do corpo da requisição. Compare o hash que você calcular com o valor do cabeçalho; se forem iguais, a requisição é autêntica. Mantenha a chave secreta em segurança e nunca a exponha no código ou em repositórios públicos.