Skip to main content
WEBHOOK

Headers

webhook-id
string
required

O ID do evento, o mesmo evt_ que vem no corpo em id. É a sua chave de idempotência: receber o mesmo webhook-id duas vezes significa a mesma coisa que recebê-lo uma vez.

Pattern: ^evt_[0-9a-z]{26}$
Example:

"evt_01h455vb4pex5vsknk084sn02e"

webhook-timestamp
integer<int64>
required

Timestamp Unix em segundos do instante do envio. Ele entra no conteúdo assinado, então recuse entregas com mais de 5 minutos de diferença do seu relógio: é o que impede que uma requisição capturada seja reenviada depois.

Example:

1741541400

webhook-signature
string
required

Uma ou mais assinaturas, separadas por espaço, cada uma no formato v1,<base64>.

A assinatura é um HMAC-SHA256 sobre {webhook-id}.{webhook-timestamp}.{corpo}, codificado em base64. A chave são os bytes do segredo do endpoint depois do prefixo, decodificados de base64 — o segredo é publicado como whsec_<base64> e fica visível no painel, em Configurações → Webhooks.

Compare com secure_compare, nunca com ==.

Durante as 24 horas seguintes a uma rotação de segredo o cabeçalho traz duas assinaturas, uma por segredo. Aceite a entrega se qualquer uma delas conferir, e você troca o segredo sem perder evento nenhum.

Example:

"v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4="

Body

application/json
object
enum<string>
required

Tipo do objeto. Sempre 'event'.

Available options:
event
Example:

"event"

type
enum<string>
required

O que aconteceu.

  • invoice.created: Fatura criada.
  • invoice.paid: Fatura paga.
  • invoice.uncollectible: Fatura dada como incobrável.
  • invoice.voided: Fatura cancelada.
  • payment_intent.created: Tentativa de cobrança criada.
  • payment_intent.failed: Tentativa de cobrança falhou.
  • payment_intent.attempts_exhausted: Sem novas tentativas de cobrança.
  • payment_intent.refund_requested: Estorno solicitado.
  • payment_intent.refunded: Estorno concluído.
  • checkout_session.completed: Sessão de checkout concluída.
  • checkout_session.expired: Sessão de checkout expirada.
  • subscription.created: Assinatura criada.
  • subscription.activated: Assinatura ativada pelo primeiro pagamento.
  • subscription.overdue: Assinatura entrou em atraso.
  • subscription.suspended: Assinatura suspensa após falhas de pagamento.
  • subscription.reactivated: Assinatura voltou para a cobrança.
  • subscription.canceled: Assinatura cancelada.
  • subscription.period_started: Novo ciclo de cobrança iniciado.
Available options:
checkout_session.completed
Example:

"invoice.paid"

live_mode
boolean
required

Indica ambiente de produção (true) ou sandbox (false).

Example:

true

data
object
required

O recurso a que o evento se refere, no mesmo formato em que GET /api/v1/<recurso>/{id} o devolve. Recursos relacionados aparecem como IDs, não aninhados.

Response

200

Responda 2xx assim que guardar o evento. Qualquer outra resposta, e um tempo acima de 15 segundos, conta como falha e entra na escada de novas tentativas.