> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turbofypay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Configure, teste e monitore webhooks da TurbofyPay com foco em seguranca, idempotencia e operacao real.

<div className="turbofy-hero">
  <span className="turbofy-eyebrow">Entrega assincrona</span>
  <h1>Configure webhooks com visibilidade operacional desde o primeiro evento</h1>

  <p className="turbofy-lead">
    Use webhooks para acompanhar cobrancas PIX sem polling constante, validar
    eventos assinados e diagnosticar falhas de entrega com mais rapidez.
  </p>
</div>

## 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.

<Note>
  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.
</Note>

<img src="https://mintcdn.com/turbofypay/d0Je5_mZrDl-yvV7/images/webhooks/01-visao-geral-webhooks.png?fit=max&auto=format&n=d0Je5_mZrDl-yvV7&q=85&s=e6966202a8d10b50f2d27ead70662760" alt="Visao geral do painel de credenciais e webhooks." width="1440" height="900" data-path="images/webhooks/01-visao-geral-webhooks.png" />

<Note>
  A mesma area operacional permite revisar credenciais, verificar endpoints
  cadastrados e atualizar o painel para conferir novas entregas.
</Note>

## 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.

<img src="https://mintcdn.com/turbofypay/d0Je5_mZrDl-yvV7/images/webhooks/02-criar-webhook.png?fit=max&auto=format&n=d0Je5_mZrDl-yvV7&q=85&s=c97365e990aee6be7d86bb889d4989ab" alt="Formulario de criacao de webhook com nome, URL HTTPS e eventos." width="1440" height="900" data-path="images/webhooks/02-criar-webhook.png" />

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:

<div className="turbofy-status-row">
  <span className="turbofy-chip turbofy-chip-green">charge.created</span>
  <span className="turbofy-chip turbofy-chip-green">charge.paid</span>
  <span className="turbofy-chip turbofy-chip-yellow">charge.expired</span>
  <span className="turbofy-chip turbofy-chip-red">charge.cancelled</span>
</div>

## 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`.

<img src="https://mintcdn.com/turbofypay/d0Je5_mZrDl-yvV7/images/webhooks/03-secret-webhook.png?fit=max&auto=format&n=d0Je5_mZrDl-yvV7&q=85&s=babb7b31d3f8f8169dee6bd796711ff5" alt="Aviso com o Webhook Secret gerado apos criar um endpoint." width="1440" height="900" data-path="images/webhooks/03-secret-webhook.png" />

<Warning>
  O Webhook Secret nao e o mesmo valor do `x-client-secret`. Se houver
  exposicao, rotacione imediatamente antes de continuar usando a integracao.
</Warning>

## 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

```bash theme={null}
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**.

<img src="https://mintcdn.com/turbofypay/d0Je5_mZrDl-yvV7/images/webhooks/04-historico-entregas.png?fit=max&auto=format&n=d0Je5_mZrDl-yvV7&q=85&s=2f47b41763bd9786149e31c25ed4d2cd" alt="Tabela de historico com status, HTTP e reenvio de entregas." width="1440" height="900" data-path="images/webhooks/04-historico-entregas.png" />

<Note>
  O frontend do comprador nao confirma compra nem dispara webhooks. A
  confirmacao vem do backend da TurbofyPay apos retorno do provedor.
</Note>

## 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

* Revise [Autenticacao](/integracao/autenticacao) para padrao de seguranca.
* Consulte [Criar cobranca PIX](/reference/cobranca-pix/criar-cobranca-pix) para origem dos eventos.
* Use [Indo para producao](/operacao/producao) para checklist de operacao.