Webhooks

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"
        }
    ]
}