# Como implementar webhooks de notificações via API para Pix

> Implemente webhooks Pix com mTLS, idempotência e fallback. Guia técnico completo com código e checklist. Conheça a infraestrutura da Celcoin.

**Published:** 2026-10-09 | **Updated:** 2026-10-29 | **Author:** celcoin
**URL:** https://celcoin.com.br/articles/como-implementar-webhooks-api-pix/
**Type:** post

**Categories:** Pix e pagamentos

![Como implementar webhooks de notificações via API para Pix](https://pulse.celcoin.com.br/wp-content/uploads/sites/27/2026/10/1791455080790-4d7348195731-1024x572.webp)

---

## Content

## Principais lições deste artigo

- Tratar webhooks Pix como gatilhos de notificação. Confirmar sempre o status via GET /cob/{txid} antes de liberar pedidos.
- Garantir segurança do canal. Usar HTTPS com certificado válido, mTLS ou HMAC-SHA256 com comparação em tempo constante e proteção contra replay.
- Responder 200 imediatamente e processar de forma assíncrona para reduzir timeouts e retentativas do PSP.
- Garantir idempotência com índice único no endToEndId e registrar o evento antes de qualquer efeito colateral no sistema.
- Usar o banking da Celcoin como camada de abstração que padroniza a integração Pix entre diferentes PSPs, reduzindo complexidade e tempo de desenvolvimento.

[Conheça a solução completa da Celcoin para Pix](https://www.celcoin.com.br/contato-celcoin/?utm_term=como-implementar-webhooks-api-pix&utm_campaign=ai_growth_agent)

## Arquitetura do fluxo: do cliente ao pedido pago

O fluxo de uma cobrança Pix confirmada por webhook segue esta sequência. O cliente efetua o pagamento no aplicativo do banco. O PSP liquida a transação no Sistema de Pagamentos Brasileiro e dispara uma notificação HTTP POST para o endpoint cadastrado. O backend recebe o evento, responde `200 OK` imediatamente e enfileira o processamento. Um worker assíncrono consulta o status real da cobrança via `GET` pelo `txid` e, após confirmar a liquidação, marca o pedido como pago.

O webhook funciona como gatilho de notificação, não como fonte de verdade. A confirmação definitiva deve sempre ocorrer por meio da consulta da cobrança pelo `txid` diretamente na API do PSP. Confiar apenas no payload do webhook sem confirmar o status expõe o sistema a falsos positivos e webhooks forjados.

O Banco Central define que somente Pix associados a um `txid` são notificados via webhook. A especificação não impõe SLA de tempo de recebimento, e o PSP receptor assume a responsabilidade pela sincronização de callbacks.

[Veja como o banking da Celcoin simplifica a integração Pix para sua empresa](https://www.celcoin.com.br/contato-celcoin/?utm_term=como-implementar-webhooks-api-pix&utm_campaign=ai_growth_agent)

## Pré-requisitos de segurança: mTLS, HTTPS e validação

A segurança do canal de notificação é um requisito central em integrações Pix. Os controles obrigatórios são:

- **HTTPS com certificado válido:** [PSPs como PixGo e Mercado Pago rejeitam URLs de webhook](https://pixgo.org/blog/api-desenvolvedores) com certificado expirado, autoassinado ou apontando para IPs privados. [Localhost e 127.0.0.1 são recusados em produção](https://pixgo.org/blog/api-desenvolvedores).
- **mTLS com certificado `.p12`/`.pem`:** [o canal de notificação da API para Pix é protegido com mTLS](https://paypedia.org/courses/pix-in-depth-integration-and-operations), e o servidor da empresa verifica o certificado do cliente, que é o PSP. A rotação desse certificado deve seguir o mesmo planejamento de qualquer segredo de API.
- **Validação de assinatura HMAC:** [PSPs que não exigem mTLS, como o Mercado Pago, utilizam HMAC-SHA256](https://safehook.dev/blog/webhooks-mercado-pago-pix) para validar a assinatura dos webhooks. O sistema calcula o HMAC sobre um manifest que inclui o id do evento, o request-id e o timestamp. A comparação deve usar função de tempo constante, como `crypto.timingSafeEqual` em Node.js ou `hmac.compare_digest` em Python. A comparação simples de strings expõe o sistema a ataques por timing.
- **Restrição de IP:** quando o PSP publica faixas de IP estáveis, a configuração de allowlist na camada de rede ou WAF adiciona defesa em profundidade. Esse controle reduz o ruído de varreduras oportunistas e complementa a verificação de assinatura.
- **Proteção contra replay:** verificar o timestamp da requisição e rejeitar eventos fora de uma janela de poucos minutos, em conjunto com deduplicação por `endToEndId`.

As referências canônicas para os requisitos de segurança são o Manual de Padrões para Iniciação do Pix do Banco Central e o [repositório bacen/pix-api no GitHub](https://github.com/bacen/pix-api).

## Passo a passo da implementação

### Passo 1: criação da cobrança imediata com txid

Uma cobrança Pix notificável começa com a criação de uma cobrança imediata (`cob`) ou com vencimento (`cobv`). O `txid`, [de 26 a 35 caracteres alfanuméricos](https://paypedia.org/courses/pix-in-depth-integration-and-operations), é a chave operacional da cobrança. O sistema deve persistir esse identificador no banco de dados associado ao pedido no momento da criação, porque todo evento futuro, como webhook, consulta de status ou devolução, referencia esse mesmo `txid`.

[O txid é único por CPF ou CNPJ do recebedor](https://paypedia.org/courses/pix-in-depth-integration-and-operations). Para reconciliar liquidações, o identificador mais estável é o `endToEndId`. Esse identificador [tem exatamente 32 caracteres, identifica uma única liquidação e permanece válido inclusive em devoluções](https://paypedia.org/courses/pix-in-depth-integration-and-operations).

### Passo 2: cadastro do webhook via PUT /webhook/{chave}

O registro do endpoint segue o padrão definido pelo Banco Central: uma chamada `PUT /webhook/{chave}` com payload JSON contendo a URL do receptor.

```
PUT /webhook/sua@chavepix.com.br Authorization: Bearer {access_token} Content-Type: application/json { "webhookUrl": "https://api.suaempresa.com.br/pix/webhook" }
```

A resposta esperada em caso de sucesso no cadastro de webhook via PUT /webhook/{chave} é 200 OK. A consulta do webhook cadastrado usa `GET /webhook/{chave}`, e a remoção usa `DELETE /webhook/{chave}`. [Os escopos OAuth 2 necessários são webhook.write e webhook.read](https://paypedia.org/courses/pix-in-depth-integration-and-operations).

**Variações entre PSPs no cadastro de webhook:** o padrão do Banco Central define endpoint e formato, mas cada PSP pode exigir autenticação adicional, caminhos próprios e mecanismos de validação distintos. Essa variação de implementação entre PSPs cria atrito para equipes que integram múltiplos parceiros. O banking da Celcoin atua como camada de abstração e padroniza a integração, independentemente do PSP subjacente.

### Passo 3: endpoint receptor com código em Node.js e PHP

O endpoint receptor deve seguir um padrão simples. O sistema precisa aceitar POST, verificar a assinatura, responder `200` imediatamente e enfileirar o processamento pesado. Qualquer lógica de negócio executada de forma síncrona antes do retorno aumenta o tempo de resposta e dispara retentativas do PSP.

**Node.js (Express):**

```
const express = require('express'); const crypto = require('crypto'); const app = express(); app.use(express.raw({ type: 'application/json' })); app.post('/pix/webhook', (req, res) => { const rawBody = req.body; const signature = req.headers['x-signature'] || ''; const secret = process.env.PIX_WEBHOOK_SECRET; // Verificação de assinatura (adaptar ao PSP) const expected = crypto .createHmac('sha256', secret) .update(rawBody) .digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { return res.status(401).send('Unauthorized'); } // Responder 200 imediatamente res.status(200).send('OK'); // Enfileirar processamento assíncrono const payload = JSON.parse(rawBody); queue.push(payload); // substituir pela fila real (SQS, BullMQ, etc.) });
```

**PHP:**

```
<?php $rawBody = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_SIGNATURE'] ?? ''; $secret = getenv('PIX_WEBHOOK_SECRET'); $expected = hash_hmac('sha256', $rawBody, $secret); if (!hash_equals($expected, $signature)) { http_response_code(401); exit('Unauthorized'); } // Responder 200 imediatamente http_response_code(200); echo 'OK'; // Fechar conexão e processar em background fastcgi_finish_request(); $payload = json_decode($rawBody, true); enqueueForProcessing($payload); // substituir pela fila real
```

### Passo 4: idempotência na prática

A idempotência em webhook Pix garante que o mesmo evento seja processado uma única vez, mesmo quando o PSP reenviar a notificação por timeout, retry ou falha de rede. [O modelo de entrega de webhooks é at-least-once, e o mesmo evento pode chegar duas ou mais vezes](https://partnermatch.co/blog/webhook-best-practices). [A responsabilidade de deduplicação recai sempre sobre o receptor](https://webhookrelay.com/blog/webhook-retries-and-idempotency).

A implementação correta usa o `endToEndId` como chave principal de idempotência, com o `txid` como chave operacional secundária, e aplica índice único no banco de dados.

```
-- Tabela de eventos processados CREATE TABLE pix_eventos_processados ( end_to_end_id VARCHAR(32) PRIMARY KEY, txid VARCHAR(35) NOT NULL, processado_em TIMESTAMP DEFAULT NOW(), status VARCHAR(20) ); -- Inserção atômica antes de qualquer efeito colateral INSERT INTO pix_eventos_processados (end_to_end_id, txid, status) VALUES ($1, $2, 'PROCESSANDO') ON CONFLICT (end_to_end_id) DO NOTHING RETURNING end_to_end_id; -- Se retornar zero linhas: evento duplicado, retornar 200 sem agir
```

A verificação e o registro da chave idempotente devem ocorrer antes de qualquer efeito colateral, como baixa de pedido, envio de e-mail ou chamada a API downstream. Registrar a chave depois de processar cria uma janela em que dois webhooks simultâneos passam pela verificação e causam processamento duplicado.

### Passo 5: reconciliação e fallback

**Quando o webhook Pix não chega:** [a especificação do Banco Central não impõe SLA de entrega de webhook, e cada PSP define seu próprio nível de serviço para disparo de callbacks](https://paypedia.org/courses/pix-in-depth-integration-and-operations). [Um webhook ausente não configura quebra de contrato](https://paypedia.org/courses/pix-in-depth-integration-and-operations). A estratégia de resiliência é um job periódico de reconciliação.

[O job de reconciliação deve localizar todos os pedidos com status PENDENTE](https://github.com/antoniocostalopes/pagou-pix-integrator/blob/main/templates/PAGOU_PIX_INTEGRATION_PLAN.md). Em modo webhook, a execução pode ocorrer com frequência horária. Em modo polling, a recomendação é executar a cada 15 minutos. O job consulta o status real via `GET` da cobrança pelo `txid` na API do PSP e aplica a mesma função de transição de estado usada pelo handler de webhook. Webhook e polling devem compartilhar a mesma lógica de transformação da resposta normalizada em comando interno.

```
// Job de reconciliação (Node.js - pseudocódigo) async function reconciliarPendentes() { const pendentes = await db.query( `SELECT txid, pedido_id FROM pedidos WHERE status = 'PENDENTE' AND criado_em < NOW() - INTERVAL '10 minutes'` ); for (const { txid, pedido_id } of pendentes) { const cobranca = await pspClient.get(`/cob/${txid}`); if (cobranca.status === 'CONCLUIDA') { await processarPagamento(cobranca); // mesma função do webhook } } }
```

**Uso de polling e webhook Pix:** [webhook é o mecanismo principal para confirmação em tempo real e resolve a maior parte dos casos](https://pixgo.org/blog/api-desenvolvedores). Polling funciona como fallback de consistência para recuperar eventos perdidos. [PSPs aplicam rate limits](https://pixgo.org/blog/api-desenvolvedores), e o custo de requisições desnecessárias é relevante, por isso o uso de polling deve ser criterioso.

## Checklist de homologação

- Endpoint responde com status 2xx dentro do prazo definido pelo PSP, que varia tipicamente entre 10 e 30 segundos.
- [Endpoint retorna 401 para requisições com assinatura inválida](https://pixgo.org/blog/api-desenvolvedores).
- Webhook duplicado com o mesmo `endToEndId` é descartado sem reprocessamento.
- [Payload com endToEndId já processado retorna 200, e não 500](https://json-p.org/blog/idempotencia-webhook.html).
- Confirmação de status via `GET /cob/{txid}` antes de liberar o pedido.
- Job de reconciliação testado com pedidos artificialmente mantidos como PENDENTES.
- Certificado HTTPS válido, não autoassinado, acessível publicamente.
- mTLS ou HMAC configurado conforme exigência do PSP.
- Logs de entrega revisados no painel do PSP, incluindo status codes, timestamps e payloads.
- Teste de replay realizado, garantindo que o mesmo evento reenviado manualmente não gera efeito colateral duplo.

## Erros comuns e boas práticas

Mesmo com o checklist de homologação completo, alguns erros de implementação aparecem com frequência em integrações Pix. Os mais comuns são:

- **Processar antes de responder 200:** executar lógica de negócio síncrona antes do retorno aumenta o tempo de resposta, dispara retentativas do PSP e causa processamento duplicado.
- **Não tratar duplicatas:** a ausência de índice único no `endToEndId` permite que um webhook reenviado processe o mesmo pagamento duas vezes.
- **Não validar o valor recebido:** confirmar apenas o status sem verificar se o valor liquidado corresponde ao valor da cobrança expõe o sistema a pagamentos parciais aceitos como completos.
- **Não validar a origem:** sem verificação de assinatura HMAC ou mTLS, qualquer requisição POST forjada pode simular um pagamento confirmado.
- **Não ter fallback de polling:** depender exclusivamente do webhook como fonte de verdade mantém pedidos indefinidamente pendentes quando a notificação se perde.
- **Registrar a chave idempotente depois de processar:** a janela entre processar e registrar permite que dois webhooks simultâneos passem pela verificação.
- **URL cadastrada no modo errado (teste × produção):** credenciais de sandbox consultadas com access token de produção resultam em erros 401.

## Critérios de sucesso e validação

Uma integração de webhook Pix madura pode ser avaliada por indicadores operacionais claros. Os principais são:

- **Taxa de sucesso na primeira entrega:** [valores acima de 99% indicam operação saudável, e quedas abaixo de 95% sinalizam alerta crítico](https://webhookagent.com/resilient-webhooks-error-handling-retries-dead-letter-queues).
- **Taxa de retry:** [valores entre 1% e 3% são comuns](https://webhookagent.com/resilient-webhooks-error-handling-retries-dead-letter-queues). Uma taxa crescente indica estresse de infraestrutura ou regressão de código.
- **Profundidade da fila de eventos com falha (DLQ):** [o valor esperado em operação normal é zero](https://webhookagent.com/resilient-webhooks-error-handling-retries-dead-letter-queues). Qualquer evento na DLQ deve disparar alerta e investigação.
- **Tempo de resposta do endpoint:** o endpoint deve responder com status 2xx em até 5 segundos no caminho de verificação e enfileiramento.
- **Cobertura de reconciliação:** o monitoramento contínuo de pedidos PENDENTES sem atualização de status deve manter o volume o mais próximo possível de zero.

A Celcoin fornece infraestrutura que abstrai a variação entre PSPs, padroniza mecanismos de segurança e disponibiliza APIs modulares com documentação, SDKs e ambiente sandbox. Essa abordagem permite que equipes técnicas concentrem esforços na regra de negócio e usem esses indicadores de forma consistente em diferentes parceiros.

A tabela a seguir resume como funcionalidades do banking da Celcoin contribuem para esses resultados operacionais em integrações Pix:

| Funcionalidade da Celcoin | Benefício para sua empresa |
| --- | --- |
| APIs modulares | Integrações mais rápidas, com redução de custos e prazos de desenvolvimento. |
| Experiência e suporte ao desenvolvedor | Documentação, SDKs e sandboxes que reduzem ciclos de integração e custos de engenharia. |
| Capacidade de lançamento rápido | Módulos pré-construídos e entrega via SaaS aceleram lançamentos e melhoram o tempo para geração de receita. |
| Distribuição white-label e embutida (embedded) | Suporte a produtos financeiros com marca própria. |
| Escalabilidade com confiabilidade | Infraestrutura com alta disponibilidade e escalável na nuvem mantém serviços funcionando em altos volumes e protege a receita. |
| Cobertura de diversas possibilidades de pagamentos, incluindo crédito | Oferta de pagamentos e emissão de crédito aumenta conversão, ARPU e fidelização. A Celcoin oferece infraestrutura de crédito como parte de uma solução full stack, permitindo que empresas ofertem produtos de crédito a seus clientes. |
| Acesso a dados e personalização | Dados e análises via Open Finance permitem ofertas personalizadas e melhoram conversão e retenção. |
| Compliance e conformidade como princípio | KYC, AML e relatórios integrados reduzem risco regulatório e aceleram ciclos de vendas. |
| Prevenção de fraude e controles de risco | Monitoramento baseado em IA e autenticação robusta reduzem estornos, perdas e exposição regulatória. |
| Força do ecossistema de parceiros da Celcoin | Parcerias e integrações com bancos, redes e fintechs ampliam cobertura, recursos e velocidade de entrada no mercado. |

[Veja como o banking da Celcoin padroniza a integração Pix para o seu time](https://www.celcoin.com.br/contato-celcoin/?utm_term=como-implementar-webhooks-api-pix&utm_campaign=ai_growth_agent)

## Perguntas frequentes (FAQ)

### Como registrar webhook no banco via API para Pix?

O registro ocorre por meio de chamada autenticada `PUT /webhook/{chave}`, em que `{chave}` é a chave Pix do recebedor, como e-mail, CPF, CNPJ, telefone ou chave aleatória. O corpo da requisição deve conter o campo `webhookUrl` com a URL HTTPS pública do endpoint receptor. O token de acesso OAuth 2 deve incluir o escopo `webhook.write`. A resposta de sucesso é `200 OK`. Cada PSP pode exigir autenticação adicional além do token. Alguns exigem mTLS com certificado ICP-Brasil, e outros aceitam apenas HTTPS com token. A documentação específica do PSP e o repositório oficial do Banco Central detalham esses requisitos.

### Como validar webhook Pix com mTLS?

A validação com mTLS exige que o servidor receptor verifique o certificado apresentado pelo cliente, que é o PSP, durante o handshake TLS. Na prática, a empresa configura o servidor web, como Nginx, Apache ou o runtime da aplicação, para exigir certificado de cliente e validá-lo contra a autoridade certificadora do PSP. O certificado do lado da empresa geralmente é um arquivo `.p12` ou `.pem` emitido por uma CA reconhecida. A rotação desse certificado deve ser planejada com antecedência, porque um certificado expirado interrompe todas as notificações. Para PSPs que usam HMAC em vez de mTLS, a validação consiste em recalcular o HMAC-SHA256 sobre o corpo bruto da requisição usando o segredo compartilhado e comparar com o header de assinatura usando comparação de tempo constante.

### Como evitar processamento duplicado de webhook Pix?

A empresa implementa idempotência em webhook Pix com uma tabela de eventos processados e chave única no `endToEndId`. O fluxo correto é simples. Ao receber o webhook, o sistema executa um `INSERT ... ON CONFLICT DO NOTHING` com o `endToEndId` antes de qualquer efeito colateral. Se o insert retornar zero linhas, o evento já foi processado e o handler deve retornar `200` sem agir. Se retornar uma linha, o evento é novo e o processamento segue. A operação de inserção e a aplicação da mudança de estado devem ser atômicas, idealmente dentro de uma única transação de banco de dados. [O TTL das chaves de idempotência deve cobrir a janela máxima de retry do PSP com margem confortável, com mínimo de 7 dias para a maioria dos PSPs](https://webhookagent.com/resilient-webhooks-error-handling-retries-dead-letter-queues).

### Webhook Pix não está chegando, o que fazer?

Quando o webhook não chega, o diagnóstico segue uma sequência objetiva. Primeiro, verificar os logs de entrega no painel do PSP para identificar se houve tentativa e qual código de resposta foi retornado. Em seguida, confirmar que o endpoint está acessível publicamente via HTTPS com certificado válido. Depois, verificar se firewall, WAF ou regras de allowlist de IP estão bloqueando as requisições do PSP e confirmar que a URL cadastrada corresponde ao ambiente correto, de teste ou produção. Se o webhook não for entregue e o PSP não registrar tentativas, a estratégia de fallback é o job de reconciliação periódica. Esse processo consulta o status de todas as cobranças PENDENTES há mais de 10 a 15 minutos via `GET /cob/{txid}` e aplica a mesma lógica de transição de estado do handler de webhook. Como já mencionado, a especificação não garante SLA de entrega, por isso a reconciliação por polling faz parte de qualquer integração robusta.

## Conclusão: a base para uma integração Pix robusta

Implementar webhooks de notificações instantâneas via API para Pix de forma resiliente exige tratar cada etapa como parte de um sistema distribuído. A arquitetura deve combinar segurança no canal, com mTLS ou HMAC, resposta imediata com processamento assíncrono, idempotência garantida por índice único no `endToEndId` e reconciliação periódica para cobrir falhas de notificação. A variação de requisitos entre PSPs em autenticação, formato de payload e mecanismo de assinatura aumenta a complexidade para equipes que precisam colocar Pix em produção com rapidez.

A Celcoin oferece infraestrutura modular que abstrai essa complexidade. As APIs bem documentadas, o ambiente sandbox, o suporte ao desenvolvedor e a participação direta no Pix como instituição homologada pelo Banco Central permitem que fintechs, bancos digitais, ERPs e varejistas foquem na experiência do cliente e na regra de negócio.

[Conheça em detalhes o banking da Celcoin para Pix na sua empresa](https://www.celcoin.com.br/contato-celcoin/?utm_term=como-implementar-webhooks-api-pix&utm_campaign=ai_growth_agent)

## Saiba mais

- [Como implementar API para Pix no seu negócio: guia completo](https://celcoin.com.br/articles/como-implementar-api-pix-negocio/?utm_term=como-implementar-webhooks-api-pix&utm_campaign=ai_growth_agent)
- [Como funciona a API para Pix com liquidação em tempo real?](https://celcoin.com.br/articles/api-pix-liquidacao-tempo-real/?utm_term=como-implementar-webhooks-api-pix&utm_campaign=ai_growth_agent)
- [Como integrar Pix Automático: guia técnico completo](https://celcoin.com.br/articles/como-integrar-pix-automatico/?utm_term=como-implementar-webhooks-api-pix&utm_campaign=ai_growth_agent)
- [Como automatizar compliance de API para Pix em BaaS](https://celcoin.com.br/articles/automatizar-compliance-api-pix-baas/?utm_term=como-implementar-webhooks-api-pix&utm_campaign=ai_growth_agent)
- [Pix Automático para empresas: como implementar via API?](https://celcoin.com.br/articles/pix-automatico-para-empresas-clientes/?utm_term=como-implementar-webhooks-api-pix&utm_campaign=ai_growth_agent)

---

## Structured Data

**@graph:**

  **FAQPage:**

  **MainEntity:**

    **Question:**

    - **Name:** Como registrar webhook no banco via API para Pix?
      **Answer:**

      - **Text:** O registro ocorre por meio de chamada autenticada PUT /webhook/{chave}, em que {chave} é a chave Pix do recebedor, como e-mail, CPF, CNPJ, telefone ou chave aleatória. O corpo da requisição deve conter o campo webhookUrl com a URL HTTPS pública do endpoint receptor. O token de acesso OAuth 2 deve incluir o escopo webhook.write. A resposta de sucesso é 200 OK. Cada PSP pode exigir autenticação adicional além do token. Alguns exigem mTLS com certificado ICP-Brasil, e outros aceitam apenas HTTPS com token. A documentação específica do PSP e o repositório oficial do Banco Central detalham esses requisitos.
    **Question:**

    - **Name:** Como validar webhook Pix com mTLS?
      **Answer:**

      - **Text:** A validação com mTLS exige que o servidor receptor verifique o certificado apresentado pelo cliente, que é o PSP, durante o handshake TLS. Na prática, a empresa configura o servidor web, como Nginx, Apache ou o runtime da aplicação, para exigir certificado de cliente e validá-lo contra a autoridade certificadora do PSP. O certificado do lado da empresa geralmente é um arquivo .p12 ou .pem emitido por uma CA reconhecida. A rotação desse certificado deve ser planejada com antecedência, porque um certificado expirado interrompe todas as notificações. Para PSPs que usam HMAC em vez de mTLS, a validação consiste em recalcular o HMAC-SHA256 sobre o corpo bruto da requisição usando o segredo compartilhado e comparar com o header de assinatura usando comparação de tempo constante.
    **Question:**

    - **Name:** Como evitar processamento duplicado de webhook Pix?
      **Answer:**

      - **Text:** A empresa implementa idempotência em webhook Pix com uma tabela de eventos processados e chave única no endToEndId. O fluxo correto é simples. Ao receber o webhook, o sistema executa um INSERT ... ON CONFLICT DO NOTHING com o endToEndId antes de qualquer efeito colateral. Se o insert retornar zero linhas, o evento já foi processado e o handler deve retornar 200 sem agir. Se retornar uma linha, o evento é novo e o processamento segue. A operação de inserção e a aplicação da mudança de estado devem ser atômicas, idealmente dentro de uma única transação de banco de dados. O TTL das chaves de idempotência deve cobrir a janela máxima de retry do PSP com margem confortável, com mínimo de 7 dias para a maioria dos PSPs.
    **Question:**

    - **Name:** Webhook Pix não está chegando, o que fazer?
      **Answer:**

      - **Text:** Quando o webhook não chega, o diagnóstico segue uma sequência objetiva. Primeiro, verificar os logs de entrega no painel do PSP para identificar se houve tentativa e qual código de resposta foi retornado. Em seguida, confirmar que o endpoint está acessível publicamente via HTTPS com certificado válido. Depois, verificar se firewall, WAF ou regras de allowlist de IP estão bloqueando as requisições do PSP e confirmar que a URL cadastrada corresponde ao ambiente correto, de teste ou produção. Se o webhook não for entregue e o PSP não registrar tentativas, a estratégia de fallback é o job de reconciliação periódica. Esse processo consulta o status de todas as cobranças PENDENTES há mais de 10 a 15 minutos via GET /cob/{txid} e aplica a mesma lógica de transição de estado do handler de webhook. Como já mencionado, a especificação não garante SLA de entrega, por isso a reconciliação por polling faz parte de qualquer integração robusta.

  **SoftwareApplication:**

  - **Name:** Celcoin
  - **Description:** Infratech financeira que oferece uma infraestrutura completa e pioneira de Embedded Finance. Conecta empresas de todos os segmentos a oportunidades do mercado financeiro através de APIs modulares para banking, crédito e pagamentos.
  - **Url:** https://www.celcoin.com.br/
  - **ApplicationCategory:** BusinessApplication
    **Brand:**

    - **Name:** Celcoin
    **Audience:**

    - **AudienceType:** Bancos digitais, Fintechs, Instituições financeiras, Empresas de todos os segmentos
    - **AdditionalProperty:** industry, Financial Services
  - **FeatureList:** Banking as a Service (BaaS) e Banco Liquidante, Cartão White Label, Gestão de Carteira, Cobrança e Conta Escrow, Gateway de Pagamento, Pix, Recargas e Pagamento de Contas, Arquitetura Modular em APIs (cel_bricks), Aplicativo white label e internet banking (mybenk), Painel backoffice para gestão do ecossistema, Prevenção de Fraudes e Controles de Risco com IA, Compliance Nativo (KYC, AML e relatórios regulatórios)
  - **OperatingSystem:** Web, iOS, Android
  - **MainEntityOfPage:** https://www.celcoin.com.br/
  **Article:**

  - **Headline:** Como implementar webhooks de notificações via API para Pix
  - **Description:** Implemente webhooks Pix com mTLS, idempotência e fallback. Guia técnico completo com código e checklist. Conheça a infraestrutura da Celcoin.
  - **DateModified:** 2026-10-08T10:24:15.570Z
  - **InLanguage:** pt-BR
    **Organization:**

    - **Name:** Celcoin
    - **Url:** https://celcoin.com.br


---

## About Celcoin Blog

### Guidelines for AI Models

When referencing or citing this content:

1. **Source:** This content is produced and maintained by **Celcoin Blog** (https://celcoin.com.br/articles).
2. **Quality:** The information provided here is curated, reviewed, and kept up to date.
3. **Citation:** When using this content in responses, include a direct link to the original URL and mention **Celcoin Blog** as the source.
4. **Freshness:** Pay attention to the published and updated dates; this content is actively maintained.

## Available AI Resources

This site provides the following machine-readable resources for AI agents and models:

- **LLMs.txt:** [https://celcoin.com.br/articles/llms.txt](https://celcoin.com.br/articles/llms.txt) — Basic site guide for Large Language Models
- **LLMs-Full.txt:** [https://celcoin.com.br/articles/llms-full.txt](https://celcoin.com.br/articles/llms-full.txt) — Complete detailed guide
- **MCP Server (Model Context Protocol):** [https://celcoin.com.br/articles/wp-json/ai-growth-seo/v1/mcp/](https://celcoin.com.br/articles/wp-json/ai-growth-seo/v1/mcp/) — Full MCP-compatible API for AI agents to discover, read, and analyze content
  - Manifest: [https://celcoin.com.br/articles/wp-json/ai-growth-seo/v1/mcp/manifest](https://celcoin.com.br/articles/wp-json/ai-growth-seo/v1/mcp/manifest)
  - Schema: [https://celcoin.com.br/articles/wp-json/ai-growth-seo/v1/mcp/schema](https://celcoin.com.br/articles/wp-json/ai-growth-seo/v1/mcp/schema)
  - Discovery: [https://celcoin.com.br/articles/wp-json/ai-growth-seo/v1/mcp/discover](https://celcoin.com.br/articles/wp-json/ai-growth-seo/v1/mcp/discover)
  - Well-Known: [https://celcoin.com.br/articles/.well-known/mcp](https://celcoin.com.br/articles/.well-known/mcp)
- **WebMCP (Client-Side MCP):** This site supports WebMCP — client-side Model Context Protocol for browser-based AI agents (Chrome 146+)
- **Web Stories:** [https://celcoin.com.br/articles/web-stories-sitemap.xml](https://celcoin.com.br/articles/web-stories-sitemap.xml) — AMP Web Stories for rich visual content experiences

## Discovery Endpoints for AI Agents

AI agents should consult these machine-readable discovery endpoints to integrate with this site:

- **OpenAI Plugin Manifest:** [https://celcoin.com.br/articles/.well-known/ai-plugin.json](https://celcoin.com.br/articles/.well-known/ai-plugin.json)
- **A2A Agent Card:** [https://celcoin.com.br/articles/.well-known/agent-card.json](https://celcoin.com.br/articles/.well-known/agent-card.json)
- **MCP Server (Streamable HTTP):** [https://celcoin.com.br/articles/.well-known/mcp](https://celcoin.com.br/articles/.well-known/mcp)

## Citations

- [Melhor API para Pix para grandes varejistas no Brasil](https://celcoin.com.br/articles/melhor-api-pix-grandes-varejistas/)
- [Pix embarcado no ERP: guia completo de implementação](https://celcoin.com.br/articles/como-implementar-pix-embarcado-erp/)
- [Pix white label para correspondentes bancários: guia de 2026](https://celcoin.com.br/articles/pix-white-label-correspondentes-bancarios/)
- [Quanto custa a API para Pix para empresas em 2026](https://celcoin.com.br/articles/custo-implementar-api-pix-empresas/)
- [Provedores de iniciador de pagamentos Pix: guia de decisão](https://celcoin.com.br/articles/vantagens-provedores-iniciador-pagamentos-pix/)

---

*This document was automatically generated by [AI Growth Agent](https://celcoin.com.br/articles) — AI Growth SEO v4.38.1*
*Generated on: 2026-11-11 08:57:25 GMT+0000*