Webhooks

Um evento é o registro do que aconteceu na sua conta: uma fatura paga, uma cobrança recusada, um checkout concluído. O evento existe assim que o fato acontece, com o corpo congelado naquele instante. O webhook é como esse evento chega até você. Você cadastra uma URL, marca os tipos que quer receber, e o Simplo faz um POST assinado para lá. Os dois são coisas separadas de propósito. Se a entrega falhar, o evento continua existindo: você consulta em GET /api/v1/events e reenvia quando o seu servidor voltar.

Configurar

Crie uma rota no seu app

Uma rota HTTP pública que aceita POST com JSON, em qualquer linguagem.

Cadastre o endpoint no painel

Em Configurações → Webhooks, clique em Novo endpoint e cole a URL. Em produção ela precisa ser https://: o corpo leva o nome e o e-mail do seu cliente, a assinatura prova quem mandou, e o TLS é o que impede que alguém leia isso no caminho. No sandbox http:// também vale, que é o que faz um túnel para a sua máquina funcionar.O endereço também precisa ser da internet pública. Uma URL que resolve para a rede interna — 127.0.0.1, 10.x.x.x, 192.168.x.x, 169.254.169.254 — é recusada no cadastro, e recusada de novo na hora de cada entrega, caso o DNS passe a responder isso depois. A recusa aparece na lista de entregas do endpoint com o motivo.Cada conta cadastra até 5 endpoints. Cada um tem a sua URL, o seu filtro de eventos e o seu segredo de assinatura, então dá para mandar cobranças para um serviço e assinaturas para outro.

Marque os eventos

Um endpoint sem nenhum tipo marcado não recebe nada. Marque só o que você vai processar.

Copie o segredo e verifique a assinatura

O segredo aparece no card do endpoint, no formato whsec_.... Ele é a chave que valida que o POST veio mesmo do Simplo. Veja Verificar a assinatura.

O botão Testar manda um POST de verdade, assinado com o segredo daquele endpoint, com "type": "webhook.test" e data.object nulo. Ele serve para conferir o caminho de rede e a sua verificação. O evt_ desse POST não vira evento: não procure por ele em GET /api/v1/events.

Estrutura do payload

O corpo é o próprio evento. data.object carrega um recurso, no mesmo formato em que o endpoint dele devolve — a fatura que chega no seu servidor é byte a byte a fatura de GET /api/v1/invoices/{id}.

{
  "id": "evt_01h455vb4pex5vsknk084sn02e",
  "object": "event",
  "type": "invoice.paid",
  "created": 1741541400,
  "live_mode": true,
  "data": {
    "object": {
      "id": "in_01h455vb4pex5vsknk084sn02q",
      "object": "invoice",
      "amount_due": 2990,
      "amount_paid": 2990,
      "amount_remaining": 0,
      "created": 1741541000,
      "currency": "brl",
      "customer": "cus_01h455vb4pex5vsknk084sn02p",
      "customer_email": "joao@acme.com",
      "customer_name": "João Silva",
      "external_code": null,
      "live_mode": true,
      "paid": true,
      "payment_intent": "pi_01h455vb4pex5vsknk084sn02r",
      "status": "paid",
      "status_transitions": { "paid_at": 1741541400 },
      "subscription": "sub_01h455vb4pex5vsknk084sn02s",
      "total": 2990
    }
  }
}

id — o identificador do evento. É o mesmo valor do cabeçalho webhook-id e a sua chave de idempotência.
type — o que aconteceu.
created — timestamp Unix em segundos do instante do fato.
live_mode — true em produção, false no sandbox.
data.object — o recurso. Recursos relacionados vêm como ID (customer, subscription, payment_intent), e você busca cada um pelo endpoint dele quando precisar.

O corpo é congelado quando o fato acontece. Uma retentativa três dias depois entrega o que era verdade na hora, não o estado atual do recurso. Se você precisa do estado atual, leia o recurso pela API usando o ID que veio em data.object.id.

Eventos disponíveis

Evento	Quando dispara	`data.object`
`invoice.created`	Fatura gerada e aberta para pagamento	`invoice`
`invoice.paid`	Fatura liquidada	`invoice`
`invoice.uncollectible`	Régua de cobrança desistiu da fatura	`invoice`
`invoice.voided`	Fatura cancelada	`invoice`
`payment_intent.created`	Cobrança aberta para uma fatura	`payment_intent`
`payment_intent.failed`	Tentativa de cobrança falhou; não haverá nova automática	`payment_intent`
`payment_intent.attempts_exhausted`	Tentativas acabaram; não haverá nova automática	`payment_intent`
`payment_intent.refund_requested`	Estorno pedido, em curso na adquirente	`payment_intent`
`payment_intent.refunded`	Estorno concluído	`payment_intent`
`checkout_session.completed`	Comprador terminou o pagamento na sessão	`checkout_session`
`checkout_session.expired`	Sessão encerrada sem pagamento, pelo prazo ou pelo merchant	`checkout_session`
`subscription.created`	Assinatura criada, com item e descontos iniciais persistidos	`subscription`
`subscription.activated`	Primeiro pagamento confirmou a assinatura	`subscription`
`subscription.overdue`	Assinatura entrou em um novo episódio de atraso	`subscription`
`subscription.suspended`	Assinatura foi suspensa depois das tentativas de cobrança	`subscription`
`subscription.reactivated`	Assinatura suspensa voltou para a cobrança, ainda pendente	`subscription`
`subscription.canceled`	Assinatura foi cancelada	`subscription`
`subscription.period_started`	Primeiro ciclo ou renovação da assinatura começou	`subscription`

O schema de cada um está na referência da API.

Para liberar acesso depois de um pagamento, use invoice.paid. Ele chega para toda fatura liquidada, tenha a origem sido um checkout hospedado ou a cobrança recorrente de uma assinatura.

Os eventos de assinatura descrevem mudanças diferentes. subscription.overdue sai uma vez por episódio de atraso; receber o pagamento e limpar esse atraso não gera outro evento de ciclo de vida. subscription.reactivated significa que uma assinatura suspensa voltou para pending; o pagamento seguinte gera subscription.activated. subscription.period_started sai para cada ciclo novo, inclusive o primeiro, e uma repetição que encontra o ciclo existente não gera uma segunda cópia. Todos carregam a representação pública da assinatura em data.object. Campos internos usados pela régua de cobrança, como as datas privadas de atraso, suspensão e cancelamento, não fazem parte desse corpo.

Verificar a assinatura

Toda entrega vai assinada no padrão Standard Webhooks, com três cabeçalhos:

webhook-id: evt_01h455vb4pex5vsknk084sn02e
webhook-timestamp: 1741541400
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

A assinatura é um HMAC-SHA256 sobre {webhook-id}.{webhook-timestamp}.{corpo}, em base64. A chave são os bytes do segredo depois do prefixo whsec_, decodificados de base64. Como o timestamp entra no conteúdo assinado, uma requisição capturada não pode ser reenviada depois: recuse entregas com mais de 5 minutos de diferença do seu relógio.

Com a gem `standardwebhooks`

# Gemfile
gem "standardwebhooks"

class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    payload = StandardWebhooks::Webhook
      .new(ENV.fetch("SIMPLO_WEBHOOK_SECRET"))
      .verify(request.raw_post, request.headers)

    ReceivedEvent.create!(public_id: payload["id"], payload: payload)
    ProcessSimploEventJob.perform_later(payload["id"])

    head :ok
  rescue StandardWebhooks::WebhookVerificationError
    head :bad_request
  rescue ActiveRecord::RecordNotUnique
    # Já recebido antes. Isso é sucesso: pare aqui e responda 2xx.
    head :ok
  end
end

O verify cuida da tolerância de tempo e da comparação em tempo constante, e devolve o corpo já decodificado.

Sem a gem

Verifique sobre o corpo cru, exatamente como chegou. Reserializar o JSON muda os bytes e a assinatura deixa de conferir.

require "openssl"
require "base64"

def verified?(request, secret)
  id        = request.headers["webhook-id"]
  timestamp = request.headers["webhook-timestamp"].to_i
  header    = request.headers["webhook-signature"].to_s

  return false if (Time.now.to_i - timestamp).abs > 300

  key    = Base64.strict_decode64(secret.delete_prefix("whsec_"))
  digest = OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{timestamp}.#{request.raw_post}")
  expected = "v1,#{Base64.strict_encode64(digest)}"

  # O cabeçalho pode trazer mais de uma assinatura, separadas por espaço.
  header.split(" ").any? { ActiveSupport::SecurityUtils.secure_compare(it, expected) }
end

Bibliotecas oficiais existem para outras linguagens e verificam o mesmo cabeçalho.

Rotacionar o segredo

Rotacionar no card do endpoint gera um segredo novo. Pelas 24 horas seguintes, o cabeçalho webhook-signature traz duas assinaturas, uma por segredo, separadas por espaço. Aceite a entrega se qualquer uma conferir, e você troca o segredo no seu lado sem perder nenhum evento no meio do deploy. Depois das 24 horas, só o novo assina.

Entrega

Responda 2xx rápido

O Simplo espera até 15 segundos pela resposta, com 5 segundos de timeout de conexão. Só 2xx conta como entregue: um 3xx é a sua URL dizendo que mudou de lugar, e é você quem conserta isso no cadastro. A regra é guardar e enfileirar. Grave o corpo, responda 200, processe em job de background. Processar dentro da request é o que faz uma entrega estourar o timeout num dia de pico.

Retentativa: 10 tentativas em 93 horas

Uma entrega que falha é retentada. São dez tentativas no total, densas no começo, porque a maioria das falhas é um deploy ou um restart, e depois diárias, porque o que sobrevive a seis horas é uma indisponibilidade que precisa de conserto.

Tentativa	Espera desde a anterior	Acumulado
1	imediata	0
2	1 min	1 min
3	5 min	6 min
4	30 min	36 min
5	2 h	2,6 h
6	6 h	8,6 h
7	12 h	20,6 h
8	24 h	44,6 h
9	24 h	68,6 h
10	24 h	92,6 h

Cada tentativa aparece no painel, no card do endpoint, com o código de resposta, a duração e quando é a próxima.

Deduplique pelo `webhook-id`

Retentativa significa que o mesmo evento pode chegar duas vezes — por exemplo, quando o seu servidor processou o POST mas demorou 16 segundos para responder. O evt_ é sempre o mesmo, então guarde-o com índice único e trate a segunda chegada como sucesso.

def perform(event_id)
  return if ProcessedEvent.exists?(event_id: event_id)

  # ... processa o evento ...

  ProcessedEvent.create!(event_id: event_id)
end

A ordem também não é garantida. invoice.paid pode chegar antes de invoice.created se a primeira entrega tiver falhado. Use created para ordenar, ou leia o recurso pela API quando a ordem importar.

Saúde é informação, não interruptor

Falhas consecutivas marcam o endpoint como instável no painel. Isso não pausa nada: os próximos eventos continuam sendo enviados, e cada um roda a escada inteira de dez tentativas. Um endpoint que passa dias sem aceitar nenhuma entrega é um endereço que não existe mais, e aí sim o Simplo age — sempre avisando antes:

3 dias sem nenhuma entrega aceita: e-mail de aviso.
6 dias: segundo e-mail.
7 dias: o endpoint é desativado, e você reativa no painel quando o endereço voltar.

Uma única entrega aceita zera o relógio.

Reconciliar o que não chegou

Os eventos ficam consultáveis por 30 dias, tenham sido entregues ou não.

curl https://besimplo.com/api/v1/events?delivery_status=failed \
  -H "Authorization: ApiKey live_xxxxxxxxxxxxxxxx"

O filtro delivery_status responde à pergunta que interessa:

Valor	Significado
`delivered`	Algum endpoint respondeu 2xx.
`pending`	Ainda não chegou, e há nova tentativa agendada.
`failed`	As tentativas acabaram sem nenhuma resposta 2xx.
`not_sent`	Nenhum POST foi feito. Nenhum endpoint assinava esse tipo quando o fato aconteceu, ou você ainda não tinha endpoint nenhum.

GET /api/v1/events/{id} devolve o mesmo corpo que a entrega carregou, o que permite conferir o que você guardou contra o que o Simplo mandou.

Reenviar

curl -X POST https://besimplo.com/api/v1/events/evt_01h455vb4pex5vsknk084sn02e/resend \
  -H "Authorization: ApiKey live_xxxxxxxxxxxxxxxx"

O reenvio manda o mesmo corpo, com o mesmo evt_, para os endpoints ativos que assinam aquele tipo agora — inclusive um endpoint cadastrado depois do fato. Cada reenvio abre uma escada nova de dez tentativas. São até 3 reenvios por evento, a qualquer momento dentro dos 30 dias. O botão também está no painel, na lista de entregas de cada endpoint.

Testar localmente

Exponha o seu servidor local com ngrok ou cloudflared:

ngrok http 3000
# Cadastre a URL https://xxxx.ngrok.io/webhooks/simplo no painel

Gere uma cobrança no sandbox e pague: invoice.paid sai para os seus endpoints com live_mode: false. O botão Testar não substitui isso — ele confere o caminho e a assinatura, e um evento de verdade confere o seu processamento.

Comece por aqui

Conceitos

Configurar

Estrutura do payload

Eventos disponíveis

Verificar a assinatura

Com a gem `standardwebhooks`

Sem a gem

Rotacionar o segredo

Entrega

Responda 2xx rápido

Retentativa: 10 tentativas em 93 horas

Deduplique pelo `webhook-id`

Saúde é informação, não interruptor

Reconciliar o que não chegou

Reenviar

Testar localmente

​Configurar

​Estrutura do payload

​Eventos disponíveis

​Verificar a assinatura

​Com a gem standardwebhooks

​Sem a gem

​Rotacionar o segredo

​Entrega

​Responda 2xx rápido

​Retentativa: 10 tentativas em 93 horas

​Deduplique pelo webhook-id

​Saúde é informação, não interruptor

​Reconciliar o que não chegou

​Reenviar

​Testar localmente

Configurar

Estrutura do payload

Eventos disponíveis

Verificar a assinatura

Com a gem `standardwebhooks`

Sem a gem

Rotacionar o segredo

Entrega

Responda 2xx rápido

Retentativa: 10 tentativas em 93 horas

Deduplique pelo `webhook-id`

Saúde é informação, não interruptor

Reconciliar o que não chegou

Reenviar

Testar localmente