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

%%{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

2. Falha e reprocessamento

%%{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

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.