Outbound events
Cada app informa uma URL do seu produto: Apps → o app → Outbound webhook.
Eventos
session.paidum pagamento foi aprovado (também cada ciclo pago de subscription)
session.failedo pagamento foi recusado
session.expiredo checkout expirou sem pagamento
session.refundedo pagamento foi reembolsado
session.disputedo banco do cliente abriu um chargeback; data.session.dispute diz quanto, por quê e até quando responder
session.dispute_closedo banco decidiu a disputa; data.session.dispute.status é won ou lost
subscription.activatedprimeiro pagamento, ou recuperada depois de past_due
subscription.renewedum ciclo seguinte foi pago
subscription.updatedum campo mudou e o status não: o fim do período conhecido depois da ativação, o próximo período, um cancelamento agendado no gateway
subscription.past_dueuma renovação falhou; o gateway continua tentando
subscription.cancelingum cancelamento foi pedido; continua ativa até cancel_at
subscription.resumedum cancelamento agendado foi desfeito; cancel_at volta a null
subscription.canceleda subscription terminou
pingEnviar evento de teste, na página do app
Payload
Toda entrega usa o mesmo envelope: id (a entrega, também em X-Pay-Event-Id), type, created_at, livemode (false em gateways sandbox) e data. Eventos de session trazem data.session, o mesmo objeto que GET /api/v1/sessions/:id devolve; eventos de subscription trazem data.subscription, o mesmo de GET /api/v1/subscriptions/:id.
session.paid
{ "id": "0f8e2c4a-6d1b-4c3e-9a7f-2b5d8e1c4a90", "type": "session.paid", "created_at": "2026-09-25T12:00:00Z", "livemode": false, "data": { "session": { "id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12", "status": "paid", "amount": "49.90", "refunded_amount": "0.0", "currency": "BRL", "method": "card", "connection_test": false, "subscription_id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12", "gateway": { "id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12", "name": "stripe-br", "provider": "stripe", "sandbox": true }, "metadata": { "plan": "pro", "account_id": "acc_42" }, "customer": { "id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12", "external_ref": "user_42", "email": "[email protected]", "name": "Ana Souza", "document": "123.456.789-09", "phone": "+55 11 99999-0000", "address_line1": "Av. Paulista", "address_line2": null, "address_number": "1000", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "zipcode": "01310-100", "country": "BR" }, "dispute": { "id": "dp_1QxYz", "status": "needs_response", "reason": "fraudulent", "amount": "49.90", "due_by": "2026-09-25T12:00:00Z", "opened_at": "2026-09-25T12:00:00Z", "closed_at": "2026-09-25T12:00:00Z" }, "return_to": "https://yourapp.com/billing/callback", "expires_at": "2026-09-25T12:00:00Z", "created_at": "2026-09-25T12:00:00Z", "updated_at": "2026-09-25T12:00:00Z" } } }
subscription.activated
{ "id": "0f8e2c4a-6d1b-4c3e-9a7f-2b5d8e1c4a90", "type": "subscription.activated", "created_at": "2026-09-25T12:00:00Z", "livemode": false, "data": { "subscription": { "id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12", "status": "active", "amount": "49.90", "currency": "BRL", "interval": "month", "description": "Pro plan", "gateway": { "id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12", "name": "stripe-br", "provider": "stripe", "sandbox": true }, "customer": { "id": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12", "external_ref": "user_42", "email": "[email protected]", "name": "Ana Souza", "document": "123.456.789-09", "phone": "+55 11 99999-0000", "address_line1": "Av. Paulista", "address_line2": null, "address_number": "1000", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "zipcode": "01310-100", "country": "BR" }, "metadata": { "plan": "pro", "account_id": "acc_42" }, "current_period_end": "2026-09-25T12:00:00Z", "cancel_at_period_end": true, "cancel_requested_at": "2026-09-25T12:00:00Z", "cancel_at": "2026-09-25T12:00:00Z", "replaces": "7f3a9c1e-2b4d-4e8f-9a1b-3c5d7e9f0a12", "canceled_at": "2026-09-25T12:00:00Z", "created_at": "2026-09-25T12:00:00Z", "links": { "self": "https://example.com" } } } }
metadata é o que o seu produto mandou no /connect, devolvido de volta; os ciclos de renovação de uma subscription também trazem, mais description e billing_reason. customer.external_ref é o seu próprio id. A referência da API descreve cada campo.
Entrega
- 1Responda 2xx para aceitar. Qualquer outra resposta, inclusive redirects, é tentada de novo com esperas crescentes, 8 tentativas no total.
- 2Elimine duplicados pelo X-Pay-Event-Id: um reenvio mantém o mesmo id.
- 3Headers próprios (um token Authorization que seu app espera, por exemplo) são configurados com a URL, na página do app.
- 4Webhooks → Enviados lista cada entrega com a resposta e um botão Reenviar.
Próximos: Verificar a assinatura