Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.besimplo.com/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks são a forma do Simplo te avisar quando algo acontece — sem você precisar ficar consultando a API em loop. Você configura uma URL pública na sua conta. Quando um evento ocorre, o Simplo envia um POST com JSON para essa URL.

​
Configurar

1

Crie um endpoint no seu app

Uma rota HTTP pública que aceita POST com JSON. Pode ser em qualquer linguagem ou framework.
2

Cadastre a URL no painel

No Simplo, vá em Configurações → Webhooks e cole a URL (https://, não http://).
3

Escolha os eventos

Marque quais tipos você quer receber (ou marque todos).

​
Eventos disponíveis

EventoQuando dispara
invoice.createdFatura foi gerada (ainda não paga)
invoice.paidFatura recebeu pagamento confirmado
invoice.voidedFatura foi cancelada
charge.createdCobrança foi tentada (boleto/cartão/Pix gerado)
charge.refundedCobrança foi reembolsada (total ou parcialmente)
charge.rejectedCobrança foi recusada (cartão negado, etc.)
A lista completa, com schema de cada payload, está na referência da API.

​
Estrutura do payload

Todo webhook tem o mesmo envelope: 
{
  "event": {
    "id": "nevt_01h455vb4pex5vsknk084sn02e",
    "type": "invoice.paid",
    "created_at": 1741541400,
    "data": {
      "invoice": {
        "id": "in_01h455vb4pex5vsknk084sn02q",
        "status": "paid",
        "amount": 2990,
        "paid_at": 1741541400
      },
      "customer": {
        "id": "cus_01h455vb4pex5vsknk084sn02p"
      },
      "subscription": {
        "id": "sub_01h455vb4pex5vsknk084sn02s"
      }
    }
  }
}
  • event.id — identificador único do evento. Use para deduplicação no seu lado (veja abaixo).
  • event.type — qual evento aconteceu.
  • event.created_at — timestamp Unix em segundos.
  • event.data — os recursos relacionados.

​
Boas práticas

​
1. Responda rápido (timeout de 15s)

O Simplo aguarda até 15 segundos pela resposta (com timeout de conexão de 5 segundos). Se passar disso, a entrega é marcada como falha e o evento não é reentregue automaticamente. A regra de ouro: valide e enfileire. Não processe o evento direto na request — armazene o payload, retorne 200 rápido, e processe em job de background. 
# Rails — controller do webhook
class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    event = SimploEvent.create!(payload: request.raw_post)
    ProcessSimploEventJob.perform_later(event.id)
    head :ok
  end
end

​
2. Deduplique pelo event.id

Mesmo que o Simplo entregue cada evento uma única vez hoje, é recomendável deduplicar pelo event.id no seu lado — isso te protege contra reprocessamento acidental do seu próprio sistema (re-deploy, replay manual de fila, etc.): 
def perform(event_id)
  return if ProcessedEvent.exists?(event_id: event_id)

  # ... processa o evento ...

  ProcessedEvent.create!(event_id: event_id)
end

​
3. Sempre retorne 2xx no sucesso

Códigos 200, 201, 204 são todos válidos. Qualquer 4xx ou 5xx é tratado como falha.

​
4. Cada evento é entregue uma única vez

Hoje o Simplo não faz retry automático de webhooks com falha. Cada evento é entregue uma única vez — se sua URL retornar erro ou estourar o timeout de 15 segundos, o evento fica marcado como falho e não é reentregue. Por isso vale extra cuidado:
  • Sempre retorne 2xx rapidamente, mesmo que o processamento ainda não tenha acontecido (use jobs de background).
  • Logue o event.id em todas as falhas — você pode precisar reprocessar manualmente.
  • Monitore a saúde do seu endpoint. Toda entrega (sucesso ou falha) fica registrada no painel.

​
5. Saúde do webhook e desativação automática

Para proteger sua integração contra endpoints quebrados, o Simplo monitora falhas consecutivas:
  • A cada falha, um contador de falhas consecutivas incrementa.
  • A cada sucesso, o contador volta a zero.
  • Após 5 falhas consecutivas, o webhook é marcado como unhealthy e as próximas entregas são pausadas.
  • O dono da conta recebe uma notificação avisando da pausa.
Para reativar, conserte seu endpoint e vá em Configurações → Webhooks no painel para retomar as entregas.
Como não há retry automático, todo evento perdido durante o período de falha precisa ser reprocessado manualmente — geralmente consultando a API para reconstruir o estado.

​
Testar localmente

Use ferramentas como ngrok ou cloudflared para expor seu servidor local: 
ngrok http 3000
# Cole a URL https://xxxx.ngrok.io/webhooks/simplo no painel
Para ver eventos reais, gere uma cobrança no ambiente de sandbox — a fatura paga dispara invoice.paid para sua URL.