Skip to main content
Entrega assincrona

​
Configure webhooks com visibilidade operacional desde o primeiro evento

Use webhooks para acompanhar cobrancas PIX sem polling constante, validar eventos assinados e diagnosticar falhas de entrega com mais rapidez.

​
O que sao webhooks

Webhooks enviam eventos para uma URL do seu sistema quando algo importante acontece, como mudanca de status de pagamento. Isso reduz latencia operacional, evita consultas repetidas e facilita conciliacao automatica.

​
Endpoints

  • POST /sellers/webhooks/
  • GET /sellers/webhooks/

​
Onde configurar no painel

No painel TurbofyPay, a tela Credenciais e Webhooks concentra credenciais da API, cadastro de endpoints, secret de assinatura e historico de entregas.
Os prints desta pagina usam a area principal real da plataforma. Para seguranca da documentacao publica, os recortes nao exibem sidebar, perfil, topbar, menu interno ou rotas sensiveis do painel.
Visao geral do painel de credenciais e webhooks.
A mesma area operacional permite revisar credenciais, verificar endpoints cadastrados e atualizar o painel para conferir novas entregas.

​
Antes de criar um webhook

  • Use uma URL HTTPS sob seu controle.
  • Prepare o endpoint para receber eventos repetidos sem efeitos duplicados.
  • Valide assinatura ou segredo antes de confirmar processamento.
  • Nao exponha endpoints internos ou sem autenticacao adequada.
  • Registre logs suficientes para auditoria, sem armazenar dados sensiveis em excesso.

​
Criando um endpoint

Cadastre um nome facil de reconhecer, informe a URL de destino e selecione somente os eventos realmente necessarios para o seu fluxo. Formulario de criacao de webhook com nome, URL HTTPS e eventos.
  1. Use um nome operacional que identifique o sistema destino.
  2. Em producao, prefira sempre URL HTTPS.
  3. Reduza ruido operacional selecionando apenas os eventos necessarios.

​
Eventos de cobranca

No fluxo com webhook_url em POST /sellers/pix, os eventos esperados sao:
charge.createdcharge.paidcharge.expiredcharge.cancelled

​
Webhook Secret e validacao

Ao criar ou rotacionar um webhook, o painel exibe o Webhook Secret uma vez. Esse valor deve ser armazenado em local seguro e usado para validar a assinatura recebida no header turbofy-signature. Aviso com o Webhook Secret gerado apos criar um endpoint.
O Webhook Secret nao e o mesmo valor do x-client-secret. Se houver exposicao, rotacione imediatamente antes de continuar usando a integracao.

​
Fluxo recomendado de implementacao

  1. Exponha um endpoint HTTPS publico para callbacks.
  2. Registre o webhook no painel ou via POST /sellers/webhooks/.
  3. Persista o evento antes de executar regra de negocio.
  4. Aplique idempotencia por eventId ou hash estavel do payload.
  5. Responda 2xx somente quando o processamento estiver confirmado.

​
Exemplo pratico de endpoint receptor

POST /webhooks/turbofy
Content-Type: application/json
Boas praticas no handler:
  • valide origem e assinatura quando disponivel;
  • persista o payload bruto para auditoria;
  • processe com idempotencia por eventId;
  • retorne 2xx apenas apos gravar com sucesso.

​
Historico de entregas

Use o historico para acompanhar evento, destino, status, HTTP, tentativa e data. Se uma entrega falhar, corrija o endpoint antes de usar Reenviar. Tabela de historico com status, HTTP e reenvio de entregas.
O frontend do comprador nao confirma compra nem dispara webhooks. A confirmacao vem do backend da TurbofyPay apos retorno do provedor.

​
Confiabilidade operacional

  • Handler com timeout curto e tratamento de erro previsivel.
  • Retentativa interna com fila quando houver dependencia externa.
  • Observabilidade com traceId, eventId e status do processamento.
  • Alertas para falhas de entrega e aumento de latencia.

​
Seguranca

Se houver assinatura nos callbacks, valide sempre o payload bruto (rawBody) e aplique janela de tempo para mitigar replay.

​
Proximos passos

Last modified on June 1, 2026