Webhooks
Nesta página
Como integrarEventosO que chega no seu endpointAssinaturaResposta esperada e retentativasReceba no seu sistema um aviso quando uma fatura, uma assinatura ou uma contestação muda, nos eventos da tabela abaixo, sem precisar consultar a API. A mudança sem evento, como o QR Code vencido, se confere consultando o recurso.
Como integrar
Informe o endereço do seu sistema e os eventos que ele recebe.
2. Assinatura dos webhooksConfira X-Webhook-Signature antes de processar o aviso.
Leia em data o recurso que mudou.
Veja o que foi enviado e o que o seu endpoint respondeu.
5. Reenviar entregasMande de novo, na hora, a entrega que o seu sistema perdeu.
Depois do cadastro, o webhook aceita estas operações:
| Operação | Página |
|---|---|
| Listar e consultar | Consultar webhooks |
| Trocar o endereço ou os eventos, pausar e reativar | Alterar um webhook |
| Gerar um segredo novo | Trocar o segredo do webhook |
| Apagar | Excluir um webhook |
Eventos
| Evento | Quando dispara |
|---|---|
invoice.created | Fatura criada: avulsa, de adesão, de ciclo da assinatura ou pela compra no link de pagamento. Chega pending, com payments vazio. |
invoice.paid | Fatura paga. Também quando um pagamento confirmado depois leva a fatura canceled ou expired a paid. |
invoice.payment_failed | Uma tentativa passou a failed, com a fatura ainda pending: cartão ou Pix recusado, inclusive no ciclo da assinatura, ou cartão sem resposta da adquirente que terminou sem desfecho. O QR Code vencido não dispara. |
invoice.payment_refunded | Um pagamento confirmado numa fatura já paid, refunded ou chargedback foi devolvido. O status da fatura não muda. |
invoice.expired | A fatura passou de billing.expires_at sem pagamento. Na fatura de ciclo e na de adesão, sai antes de subscription.canceled. |
invoice.canceled | Você cancelou a fatura, sozinha ou junto com a assinatura, inclusive num estorno pedido por você que cancela a assinatura. Sai um evento por fatura. A fatura fechada pela contestação, pelo estorno que chega pela adquirente ou pelo fim da carência não dispara. |
invoice.refund_requested | Estorno do Pix pedido e ainda não confirmado: o estorno em refunds está requested e a fatura segue paid. A devolução automática do pagamento em duplicidade não dispara. |
invoice.refund_failed | Estorno recusado: o estorno em refunds passou a failed. Na devolução automática do pagamento em duplicidade, sai no máximo uma vez. O status da fatura não muda. |
invoice.refunded | A fatura passou a refunded, com o estorno confirmado da tentativa que a quitou. |
invoice.chargedback | A fatura passou a chargedback, e a contestação recebida no cartão que a quitou vem no campo chargeback. |
subscription.created | Assinatura criada, no cartão ou no Pix. Chega incomplete. |
subscription.activated | A fatura de adesão foi paga, e a assinatura passou de incomplete a active. |
subscription.renewed | Uma fatura de ciclo foi paga com a assinatura active, por qualquer caminho. grace volta a null e, no cartão, billing.next_at vai ao ciclo seguinte. |
subscription.grace_started | A carência começou, pela renovação recusada no cartão ou pela fatura de ciclo do Pix vencida. A assinatura segue active, com grace preenchido. |
subscription.updated | Assinatura alterada: valor, cartão ou metadata. |
subscription.canceled | Assinatura cancelada, com o motivo em cancellation.reason: por você, pelo fim da carência, depois de invoice.expired, pela adesão vencida, pelo estorno da fatura que cancela a assinatura ou pela contestação. |
subscription.reactivated | A assinatura cancelada voltou a active, pela reativação ou pelo pagamento de uma fatura depois do cancelamento. |
chargeback.received | Contestação recebida. |
chargeback.responded | Resposta à contestação registrada, por aceite ou por defesa. O prazo vencido sem resposta não dispara. |
Cada evento gera uma entrega para cada webhook ativo que tem o evento na lista events do cadastro. Em data, o evento traz o recurso que mudou, no mesmo formato da consulta dele na API.
O evento de teste ping sai só pelo painel, numa entrega só, sem nova tentativa. O envelope e o corpo de cada evento estão em Modelo de evento.
O que chega no seu endpoint
A PayZu faz um POST com o evento em JSON no endereço do webhook, com estes cabeçalhos:
| Cabeçalho | Conteúdo |
|---|---|
X-Webhook-Event | Tipo do evento, igual ao type do corpo. |
X-Webhook-Signature | Assinatura da entrega. |
X-Webhook-Timestamp | Valor em milissegundos, que muda a cada tentativa. |
X-Webhook-Nonce | Valor que muda a cada tentativa. |
Assinatura
Toda entrega chega assinada com o segredo do webhook. O cálculo e o código para conferir estão em Assinatura dos webhooks.
Resposta esperada e retentativas
Sua aplicação confere a assinatura, grava o aviso e responde.
- Resposta: qualquer status
2xxem até 5 segundos. O corpo da sua resposta não é lido. - Falha: outro status, timeout ou conexão recusada. Redirecionamento não é seguido, então um
3xxtambém conta como falha. - Nova tentativa: leva o mesmo corpo e uma assinatura nova.
- Endereço: a cada tentativa, a PayZu confere o endereço de novo e não conecta num domínio que resolve para endereço interno. Essa tentativa conta como falha.
- Atraso: as entregas saem em rodadas, pouco depois da mudança. Quando precisar do estado na hora, consulte a API.
| Tentativa | Sai depois da anterior |
|---|---|
| 2ª | 1 minuto |
| 3ª | 10 minutos |
| 4ª | 1 hora |
| 5ª | 6 horas |
| 6ª | 24 horas |
Depois da sexta tentativa sem 2xx, a entrega fica failed. Uma entrega pode ser reenviada em qualquer status.
O mesmo evento pode chegar mais de uma vez e fora de ordem.
Descarte a repetição pelo id do evento no registro de cada sistema que trata os avisos: ele é o mesmo em todas as tentativas, no reenvio e em todos os webhooks que recebem o evento. Compare também o created_at do evento para saber qual é o mais recente. Com o mesmo created_at, consulte o recurso pela API.