Skip to main content
Pense nos webhooks como mensagens que a Ephra envia para o seu sistema: em vez de você ficar perguntando “esse PIX já foi pago?”, a Ephra avisa você no instante em que o pagamento é confirmado.
Webhooks são somente notificações. A Ephra envia um evento quando o status de uma transação muda do lado dela — o ciclo de status é controlado pela Ephra e não existe endpoint na API para o cliente alterar o status de uma transação.

​
Por que usar webhooks?

Sem webhooks, sua aplicação precisaria perguntar para a API a cada segundo:
“Esse pagamento já foi confirmado?”
Isso é lento e desperdiça requisições. Com webhooks, a Ephra avisa você imediatamente:
“O pagamento foi confirmado. Aqui estão os dados.”
Assim você pode, na hora e sem intervenção manual:
  • liberar o pedido ou o acesso a um produto;
  • atualizar o status no seu sistema;
  • disparar e-mails ou mensagens;
  • registrar a movimentação financeira.

​
Como funciona na prática

1

Crie um endpoint no seu sistema

Uma URL HTTPS pública que vai receber os eventos. Ex.: https://seusite.com/webhooks/ephra.
2

Cadastre a URL na Ephra

Via dashboard ou pela rota POST /v1/webhook. Você escolhe quais eventos quer receber e recebe um signatureSecret.
3

Receba os POSTs

A cada mudança de status, a Ephra faz um POST com o payload da transação no seu endpoint.
4

Responda 2xx

Confirme o recebimento com qualquer status 2xx. Qualquer outra resposta entra em retentativa.
Precisa de webhook só para uma cobrança específica? Informe postbackUrl no corpo daquela cobrança — aquele endpoint recebe os eventos somente daquela transação, sem cadastrar um webhook permanente.

​
O evento que mais importa: transaction_paid

Na maioria das integrações, o evento que dispara a liberação do pedido é o transaction_paid (status: "paid"). Os demais eventos cobrem estorno, recusa, recuperação de venda, assinaturas, transferências e infrações — veja todos na seção Eventos.

Transações

transaction_created, transaction_paid, transaction_refunded, transaction_updated, card_declined.

Recuperação

sale_lost, cart_abandoned.

Assinaturas

product_canceled.

Transferências

transfer_created, transfer_completed, transfer_canceled, transfer_updated.

​
Formato do payload

Todos os webhooks de transação compartilham a mesma estrutura. Os campos variam conforme o evento, mas o esqueleto é sempre este: 
{
  "id": "9f1c8e2a-...-uuid",
  "type": "transaction",
  "event": "transaction_paid",
  "scope": "user",
  "transaction": { "id": "clx...", "amount": 10000, "status": "paid" },
  "customer": { "name": "Maria Silva", "email": "maria@email.com" },
  "company": { "name": "Sua Empresa", "document": "11222333000181" }
}
O campo id é o identificador da entrega (não da transação). O ID da transação está em transaction.id. Use o event para rotear o tratamento no seu lado.

​
Boas práticas

Recomendações

  • Use HTTPS em todos os endpoints.
  • Valide a assinatura HMAC de cada evento — veja Segurança.
  • Seja idempotente: registre o id do evento e processe cada um uma única vez.
  • Responda 2xx somente depois de concluir (ou enfileirar) o processamento.
  • Não valide o payload inteiro com schemas rígidos — campos novos podem ser adicionados no futuro e não devem quebrar seu endpoint.

Próximo passo: segurança

Como validar a assinatura HMAC, garantir idempotência e lidar com retentativas.