Os Webhooks são notificações enviadas pelo PagBank para seu servidor sempre que um evento ocorre. Para ser notificado sobre eventos que acontecem na sua conta de Assinaturas, você deve cadastrar um ou mais URLs como endereços de recebimento das notificações, nas configurações de preferências. Para entender como alterar as configurações de preferências e cadastrar um URL de recebimento, acesse a página de Preferências de notificação da documentação.
Eventos de webhook
A API de Pagamentos Recorrentes do PagBank gera webhooks a partir de cinco tipos de eventos:
- Planos
- Cupons
- Assinantes
- Assinaturas
- Estornos de pagamento
Cupons
Os webhooks de planos estão vinculados aos eventos de criação, atualização, ativação e desativação de um plano, como descritos abaixo:
| Evento | Descrição |
|---|---|
plan.created | Criação de um plano. |
plan.updated | Atualização de um plano. |
plan.activated | Ativação de um plano. |
plan.inactivated | Desativação de um plano. |
Cupons
Os webhooks de cupons estão vinculados aos eventos de criação, ativação e desativação de um cupom, como descritos abaixo:
| Evento | Descrição |
|---|---|
coupon.created | Criação de um cupom. |
coupon.activated | Ativação de um cupom. |
coupon.inactivated | Desativação de um cupom. |
Assinantes
Os webhooks de assinantes estão vinculados aos eventos de criação e atualização de um assinantes, e atualização de dados de cobrança do assinante, como descritos abaixo:
| Evento | Descrição |
|---|---|
customer.created | Criação de um assinante. |
customer.updated | Atualização de um assinante. |
customer.billing_info.updated | Atualização do faturamento de um assinante. |
Assinaturas
Os webhooks de assinaturas estão vinculados aos eventos de incialização, atualização, ativação e suspensão, cobrança, expiração, cancelamento e mudança de plano de uma assinatura, como descritos abaixo:
| Evento | Descrição |
|---|---|
subscription.initial | Criação de uma assinatura. |
subscription.updated | Atualização de uma assinatura. |
subscription.activated | Ativação de uma assinatura. |
subscription.suspended | Suspenção de uma assinatura. |
subscription.recurrence | Cobrança de uma assinatura. |
subscription.expired | Expiração de uma assinatura. |
subscription.canceled | Cancelamento de uma assinatura. |
subscription.migrated | Upgrade ou downgrade do Plano de uma assinatura. |
Estornos de pagamento
Os webhooks de pagamentos estão vinculados aos eventos de criação de um estorno, como descrito abaixo:
| Evento | Descrição |
|---|---|
refund.created | Criação de estorno de pagamento. |
Exemplo de webhook
A seguir você encontra um exemplo de Webhook enviado no caso de um evento de assinaturas.
{
"env": "qa",
"event": "subscription.initial | .updated | .suspended | .activated | .recurrence | .expired | .canceled | .migrated",
"resource": {
"amount": {
"currency": "BRL",
"value": 10000
},
"coupon": {
"discount": {
"type": "PERCENT",
"value": 10000
},
"id": "COUP_FA8BE965-9264-443A-A148-38C70478A1C6"
},
"created_at": "2022-06-20T18:06:43.275-03:00",
"customer": {
"email": "[email protected]",
"id": "CUST_5226051F-77F5-4CF2-AAC0-F57F2A8582D2",
"name": "Bruno Silva"
},
"exp_at": "2030-09-20",
"id": "SUBS_5AAE1F81-29D3-41BC-F043-4BC69BA85D1C",
"next_invoice_at": "2022-07-20",
"payment_method": [
{
"card": {
"brand": "visa",
"exp_month": "11",
"exp_year": "2034",
"first_digits": "411111",
"holder": {
"name": "Bruno Silva"
},
"last_digits": "1111",
"token": "TOKE_EC40****************************77D0"
},
"type": "CREDIT_CARD"
}
],
"plan": {
"id": "PLAN_9DB0D197-137F-4BC4-BECB-C93EB226F34B",
"name": "Plano Teste"
},
"pro_rata": false,
"reference_id": "subscription-g",
"status": "OVERDUE",
"updated_at": "2022-06-20T18:06:44.809-03:00"
},
"links": [
{
"href": "https://sandbox.api.assinaturas.pagseguro.com/subscriptions",
"media": "application/json",
"rel": "SELF",
"type": "GET"
},
{
"href": "https://sandbox.api.assinaturas.pagseguro.com/subscriptions/SUBS_5AAE1F81-29D3-41BC-F043-4BC69BA85D1C",
"media": "application/json",
"rel": "SELF",
"type": "GET"
},
{
"href": "https://sandbox.api.assinaturas.pagseguro.com/subscriptions/SUBS_5AAE1F81-29D3-41BC-F043-4BC69BA85D1C/suspend",
"media": "application/json",
"rel": "SELF",
"type": "PUT"
},
{
"href": "https://sandbox.api.assinaturas.pagseguro.com/subscriptions/SUBS_5AAE1F81-29D3-41BC-F043-4BC69BA85D1C/cancel",
"media": "application/json",
"rel": "SELF",
"type": "PUT"
},
{
"href": "https://sandbox.api.assinaturas.pagseguro.com/subscriptions/SUBS_5AAE1F81-29D3-41BC-F043-4BC69BA85D1C/activate",
"media": "application/json",
"rel": "SELF",
"type": "PUT"
},
{
"href": "https://sandbox.api.assinaturas.pagseguro.com/subscriptions/SUBS_5AAE1F81-29D3-41BC-F043-4BC69BA85D1C",
"media": "application/json",
"rel": "SELF",
"type": "PUT"
},
{
"href": "https://sandbox.api.assinaturas.pagseguro.com/subscriptions/SUBS_5AAE1F81-29D3-41BC-F043-4BC69BA85D1C/coupons",
"media": "application/json",
"rel": "SELF",
"type": "DELETE"
},
{
"href": "https://sandbox.api.assinaturas.pagseguro.com/subscriptions/SUBS_5AAE1F81-29D3-41BC-F043-4BC69BA85D1C/invoices",
"media": "application/json",
"rel": "INVOICE",
"type": "GET"
}
]
}
Confirmando autenticidade da notificação
É importante se certificar de que as notificações enviadas ao seu sistema são de propriedade e origem do Pagbank e que o conteúdo não foi manipulado ou sofreu nenhuma intervenção externa. Dessa forma, você pode fazer uma confirmação de autenticidade e garantir a integridade das notificações recebidas pelo seu sistema.
Acesse a página Confirmar autenticidade da notificação para aprender como como confirmar a autenticidade da notificação usando SHA256.