---
updatedAt: 2026-09-01T13:50:42.000Z
agentTools:
  projectIndex: https://docs.asaas.com/llms.txt
---

# Webhook recebido, mas não persistido

Esse erro ocorre quando o endpoint recebe o webhook, mas o evento não é salvo antes do início do processamento.

Diferentemente do erro de timeout, a requisição pode ter sido aceita normalmente. O problema surge quando o processamento falha e não existe um registro para consulta, auditoria ou reprocessamento.

### Como identificar

* não existe registro do payload recebido;
* somente eventos processados com sucesso aparecem no histórico;
* não há status para eventos recebidos ou com erro;
* o sistema não consegue confirmar se o webhook chegou;
* eventos com falha não podem ser reprocessados;
* há divergência de status sem informações suficientes para diagnóstico.

### Como corrigir

1. Crie uma tabela, fila ou estrutura para armazenar os eventos.
2. Registre o payload ou os dados necessários para reprocessamento.
3. Salve o tipo do evento, o horário e os identificadores relacionados.
4. Registre o evento antes de executar a regra de negócio.
5. Defina status internos, como recebido, processado e erro.
6. Encaminhe o evento para processamento somente após a persistência.
7. Mantenha os eventos com falha disponíveis para consulta.
8. Implemente um mecanismo seguro de reprocessamento.

**Fluxo recomendado:** receber → validar → persistir → responder → processar.

### Fluxo de diagnóstico

#### 1. Persistência do recebimento

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
    A["Webhook recebido pelo endpoint"] --> B{"Existe registro do evento?"}

    B --> BSim(("Sim"))
    B --> BNao(("Não"))

    BNao --> C["Localizar onde o evento deveria ser armazenado"]
    C --> D["Criar tabela, fila ou armazenamento de eventos"]
    D --> H["Salvar payload, tipo, horário e identificadores"]

    BSim --> E{"O registro ocorreu antes do processamento?"}

    E --> ESim(("Sim"))
    E --> ENao(("Não"))
    E --> EDuvida(("Não sabe"))

    ENao --> F["Alterar a ordem do fluxo"]
    EDuvida --> G["Consultar código, logs e transações"]
    G --> F

    F --> H

    ESim --> I{"Existe status interno do evento?"}

    I --> ISim(("Sim"))
    I --> INao(("Não"))

    INao --> H
    ISim --> J["Liberar o evento para processamento"]
    H --> J

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B,E,I decisao
    class D,F,H correcao
    class G validacao
    class J sucesso
    class C analise

    class BSim,ESim,ISim respostaSim
    class BNao,ENao,INao respostaNao
    class EDuvida respostaDuvida

    linkStyle default stroke:#94A3B8,stroke-width:2px

    linkStyle 1,7,15 stroke:#22C55E,stroke-width:4px
    linkStyle 2,8,16 stroke:#EF4444,stroke-width:4px
    linkStyle 9 stroke:#8B5CF6,stroke-width:4px
```

<br />

#### 2. Falha e reprocessamento

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
    A["Evento persistido e disponível para processamento"] --> B{"O processamento terminou com sucesso?"}

    B --> BSim(("Sim"))
    B --> BNao(("Não"))

    BSim --> C["Atualizar o status para processado"]

    BNao --> D["Registrar o status de erro"]
    D --> E{"O evento pode ser reprocessado?"}

    E --> ESim(("Sim"))
    E --> ENao(("Não"))
    E --> EDuvida(("Não sabe"))

    ESim --> F["Corrigir a causa e reprocessar"]
    EDuvida --> G["Validar payload, histórico e identificadores"]
    G --> F

    ENao --> H["Implementar reprocessamento seguro"]
    H --> F

    F --> I{"O reprocessamento funcionou?"}

    I --> ISim(("Sim"))
    I --> INao(("Não"))

    ISim --> C
    INao --> J["Consultar o estado atual na API"]
    J --> K["Reconciliar a divergência"]

    C --> L["Manter histórico e monitoramento"]
    K --> L

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B,E,I decisao
    class D,F,H,K correcao
    class C,J validacao
    class L sucesso
    class G analise

    class BSim,ESim,ISim respostaSim
    class BNao,ENao,INao respostaNao
    class EDuvida respostaDuvida

    linkStyle default stroke:#94A3B8,stroke-width:2px

    linkStyle 1,6,15 stroke:#22C55E,stroke-width:4px
    linkStyle 2,7,16 stroke:#EF4444,stroke-width:4px
    linkStyle 8 stroke:#8B5CF6,stroke-width:4px
```

<br />

### Como prevenir

Torne a persistência uma etapa obrigatória antes do processamento. Mantenha status internos, histórico dos eventos e mecanismos de reprocessamento, tratamento de duplicidades e reconciliação.

> **Receber o webhook não é suficiente. O evento precisa ser registrado antes de ser processado.**

<br />

# Sibling pages

* [Webhook com timeout ou resposta demorada](https://docs.asaas.com/docs/webhook-não-processado-dentro-do-tempo-esperado.md)
* [API Key usada no ambiente errado](https://docs.asaas.com/docs/api-key-de-sandbox-usada-em-produção.md)
* [Sistema dependente apenas da resposta síncrona](https://docs.asaas.com/docs/sistema-dependente-apenas-da-resposta-síncrona.md)
* [Cobrança duplicada após retry sem idempotência](https://docs.asaas.com/docs/cobrança-duplicada-após-retry-sem-idempotência.md)
* [Entidade criada sem vínculo com o registro interno](https://docs.asaas.com/docs/entidade-criada-sem-vínculo-com-o-registro-interno.md)
* [Status local divergente do Asaas](https://docs.asaas.com/docs/status-local-divergente-do-asaas.md)
* [Requisições bloqueadas por ausência de controle de limites](https://docs.asaas.com/docs/requisições-bloqueadas-por-ausência-de-controle-de-limites.md)
* [Listagem incompleta por ausência de paginação](https://docs.asaas.com/docs/listagem-incompleta-por-ausência-de-paginação.md)
* [Webhook duplicado processado sem idempotência](https://docs.asaas.com/docs/webhook-duplicado-processado-sem-idempotência.md)