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

# Overview

> Modelo genérico de webhooks, idempotência e roteamento por contexto

Webhooks são eventos externos entregues ao DEVMOB por providers. A seção de Webhooks descreve a regra comum de entrada, rastreabilidade, idempotência e roteamento para o contexto de negócio responsável pelo efeito.

## Responsabilidade

O recebimento de webhook tem três responsabilidades:

* Registrar a entrega externa de forma rastreável.
* Garantir idempotência por provider e identificador externo do evento.
* Traduzir eventos reconhecidos para efeitos de negócio em um contexto específico.

```mermaid theme={null}
flowchart TD
    P["Provider externo"] --> W["Webhook recebido"]
    W --> R["Registro genérico"]
    R --> I{"Evento já recebido?"}
    I -->|Sim| D["Entrega duplicada reconhecida"]
    I -->|Não| M["Mapeamento por contexto"]
    M --> E["Efeito de negócio"]
```

## Idempotência

Um webhook é identificado pelo par `externalProvider` + `externalEventId`. Esse par representa o mesmo evento externo, mesmo que o provider entregue o payload mais de uma vez.

| Situação               | Comportamento                                                                               |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| Primeira entrega       | O evento é registrado e encaminhado para o contexto responsável.                            |
| Entrega repetida       | O registro existente é preservado, `receivedCount` aumenta e `lastReceivedAt` é atualizado. |
| Evento já processado   | O efeito de negócio não é duplicado.                                                        |
| Falha no processamento | O erro fica registrado para acompanhamento e retry operacional.                             |

## Modelo genérico

O modelo genérico de webhook é independente do provider e do contexto de negócio. Ele guarda os identificadores externos, o payload original, a ação derivada e o estado de processamento.

| Campo               | Papel                                                 |
| ------------------- | ----------------------------------------------------- |
| `webhookId`         | Identificador interno do registro.                    |
| `externalProvider`  | Provider que entregou o evento.                       |
| `externalEventId`   | Identificador único do evento no provider.            |
| `externalEventType` | Tipo original do evento no provider.                  |
| `actionType`        | Ação interna derivada do evento.                      |
| `payload`           | Conteúdo original recebido.                           |
| `status`            | Estado de processamento do webhook.                   |
| `receivedCount`     | Quantidade de entregas recebidas para o mesmo evento. |
| `lastReceivedAt`    | Data da última entrega recebida.                      |
| `processedAt`       | Data do processamento bem-sucedido, quando houver.    |

Veja a modelagem completa em [Webhook](/data-modelling/webhooks/webhook).

## Contextos

<CardGroup cols={2}>
  <Card title="Billing" icon="money-bill-transfer" href="/webhooks/billing/overview">
    Eventos externos de billing mapeados para pagamento, pedido, recebíveis, transferência e conta bancária.
  </Card>
</CardGroup>