PayZu GatewayEventos de webhook

Assinatura alterada

WEBHOOKsubscription.updated

Confira o passo a passo → https://docs.payzu.com.br/docs/gateway/webhooks


Sai a cada alteração aceita do valor, do cartão ou do metadata da assinatura.

Headers

X-Webhook-Eventstringobrigatório
Evento. O mesmo de type no corpo.subscription.updated
X-Webhook-Timestampstringobrigatório
Instante desta tentativa, em milissegundos (Unix). Muda a cada tentativa e entra na assinatura.
X-Webhook-Noncestringobrigatório
Valor aleatório, novo a cada tentativa. Entra na assinatura.
X-Webhook-Signaturestringobrigatório
HMAC-SHA256, em hexadecimal, de <X-Webhook-Timestamp>.<X-Webhook-Nonce>.<corpo cru>, calculado com o segredo do webhook.

Body

idstringobrigatório
ID do evento. O mesmo em todas as tentativas, no reenvio e em todos os webhooks que recebem o evento.
typestringobrigatório
Evento. O mesmo de X-Webhook-Event.subscription.updated
created_atstringobrigatório
Data e hora do evento, em UTC. Não muda na nova tentativa nem no reenvio.
dataobjectobrigatório
O recurso do evento em subscription, como estava no momento do evento.
subscriptionobjectobrigatório
A assinatura já alterada: active na troca de valor ou de cartão; active ou canceled na troca de metadata.
idstringobrigatório
ID da assinatura.
codestringobrigatório
Código curto da assinatura.
statusstringobrigatório
Status da assinatura: active ou canceled neste evento.activecanceled
namestringobrigatório
Nome da assinatura.
amountintegerobrigatório
Valor de cada ciclo, em centavos.
recurrencestringobrigatório
Periodicidade da cobrança.monthlybimonthlyquarterlysemiannualannual
payment_methodstringobrigatório
Meio de pagamento.credit_cardpix
created_atstringobrigatório
Data e hora da criação.
updated_atstringobrigatório
Data e hora da última alteração.
credit_cardobject | nullobrigatório
Cartão da assinatura; nulo no Pix.
cardobjectobrigatório
Cartão.
idstring | nullobrigatório
ID do cartão salvo; nulo quando o cartão não ficou salvo.
brandstring | nullobrigatório
Bandeira.
last_digitsstringobrigatório
Últimos 4 dígitos.
holder_namestring | nullobrigatório
Nome impresso no cartão.
billingobjectobrigatório
Ciclos de cobrança.
anchor_atstringobrigatório
Data de referência dos ciclos.
next_atstring | nullobrigatório
Data do próximo ciclo; nula na assinatura cancelada.
canceled_atstring | nullobrigatório
Data e hora do cancelamento.
renewal_failuresintegerobrigatório
Renovações seguidas que falharam.
graceobject | nullobrigatório
Carência depois de um ciclo sem pagamento; nula sem carência.
started_atstringobrigatório
Início da carência.
ends_atstring | nullobrigatório
Fim da carência: o limite para pagar a fatura do ciclo.
cancellationobject | nullobrigatório
Cancelamento; nulo se a assinatura não está cancelada.
reasonstring | nullobrigatório
Motivo do cancelamento.initial_payment_failurerenewal_failureplan_changeinvoice_refundinvoice_chargebackcustomer_requestmerchant_requestother
notestring | nullobrigatório
Observação do cancelamento.
previous_cancellationsarray of objectsobrigatório
Cancelamentos desfeitos, do mais novo para o mais antigo; vazio se a assinatura nunca voltou de um cancelamento.
canceled_atstringobrigatório
Data e hora do cancelamento.
reasonstring | nullobrigatório
Motivo do cancelamento.initial_payment_failurerenewal_failureplan_changeinvoice_refundinvoice_chargebackcustomer_requestmerchant_requestother
notestring | nullobrigatório
Observação do cancelamento.
reactivated_atstringobrigatório
Data e hora em que a assinatura voltou a active.
customerobjectobrigatório
Cliente.
idstringobrigatório
ID do cliente.
namestringobrigatório
Nome do cliente.
emailstringobrigatório
E-mail do cliente.
documentstringobrigatório
CPF ou CNPJ do cliente.
document_typestringobrigatório
Tipo do documento.cpfcnpj
planobject | nullobrigatório
Plano de origem; nulo na assinatura avulsa.
idstringobrigatório
ID do plano.
namestringobrigatório
Nome do plano.
discountobject | nullobrigatório
Desconto dos primeiros ciclos, contando a adesão; nulo sem desconto.
typestringobrigatório
Tipo do desconto.fixed_amountpercentage
valueintegerobrigatório
Desconto: centavos ou porcentagem, conforme o tipo.
cyclesintegerobrigatório
Ciclos com desconto, contando a adesão.
internal_descriptionstring | nullobrigatório
Descrição interna do desconto.
public_descriptionstring | nullobrigatório
Texto do desconto para o cliente.
metadataobject | nullobrigatório
Seus dados, em chave e valor; nulo sem metadata.

Responses

2XXQualquer 2xx em até 5 segundos confirma a entrega. Redirecionamento conta como falha, e o corpo da resposta não é lido. Sem 2xx, a entrega volta a ser tentada 1 minuto, 10 minutos, 1 hora, 6 horas e 24 horas depois da tentativa anterior.

sem corpo

Exemploapplication/json
{  "id": "evt_MUbiqx6DLTahpw5CKSZgov",  "type": "subscription.updated",  "created_at": "2026-11-11T15:40:12.007Z",  "data": {    "subscription": {      "id": "sub_EG9uphTcCTMvYBkHPKr4cc",      "code": "EELBD9PE",      "status": "active",      "name": "Plano Mensal",      "amount": 16990,      "recurrence": "monthly",      "payment_method": "credit_card",      "created_at": "2026-11-11T15:20:59.359Z",      "updated_at": "2026-11-11T15:40:12.007Z",      "credit_card": {        "card": {          "id": "card_GL2pIWf5pznF4qwg2KKd5v",          "brand": "visa",          "last_digits": "1111",          "holder_name": "MARIA SOUZA"        }      },      "billing": {        "anchor_at": "2026-11-11T03:00:00.000Z",        "next_at": "2026-12-11T15:20:59.362Z",        "canceled_at": null,        "renewal_failures": 0      },      "grace": null,      "cancellation": null,      "previous_cancellations": [],      "customer": {        "id": "cus_bdQT0ls1QMIXVuhngvhbwC",        "name": "Maria Souza",        "email": "maria@exemplo.com.br",        "document": "52998224725",        "document_type": "cpf"      },      "plan": {        "id": "plan_oOsn4Cs4eayZ3LoytwzErn",        "name": "Plano Mensal"      },      "discount": {        "type": "percentage",        "value": 10,        "cycles": 3,        "internal_description": "Campanha de novembro",        "public_description": "10% nos 3 primeiros meses"      },      "metadata": {        "internal_id": "5678"      }    }  }}