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

# Webhook

> Registro de eventos externos recebidos, com idempotência e status de processamento

## Campos

| Campo               | Tipo                | Descrição                                              |
| ------------------- | ------------------- | ------------------------------------------------------ |
| `webhookId`         | `UUID`              | Identificador único                                    |
| `externalProvider`  | `String`            | Nome do provider externo                               |
| `externalEventId`   | `String`            | ID do evento no provider                               |
| `externalEventType` | `String`            | Tipo do evento no provider                             |
| `actionType`        | `WebhookActionType` | Ação derivada do evento                                |
| `payload`           | `Json`              | Conteúdo original do provider                          |
| `error`             | `String?`           | Mensagem de erro do processamento                      |
| `status`            | `WebhookStatus`     | Status de processamento                                |
| `receivedCount`     | `Int`               | Número de entregas do provider para o mesmo evento     |
| `lastReceivedAt`    | `DateTime`          | Data da última entrega                                 |
| `processedAt`       | `DateTime?`         | Data do processamento bem-sucedido                     |
| `createdBy`         | `UUID?`             | Usuário que criou o registro, quando aplicável         |
| `createdAt`         | `DateTime`          | Data de criação                                        |
| `updatedBy`         | `UUID?`             | Usuário que fez a última atualização, quando aplicável |
| `updatedAt`         | `DateTime`          | Data da última atualização                             |

## Idempotência

* O par `externalProvider` + `externalEventId` identifica um evento único do provider.
* Entregas repetidas do mesmo evento são tratadas de forma idempotente.
* Consultas podem ser filtradas por provider, tipo de evento, ação, status e data.

## Regras de Negócio

* Cada entrega repetida do mesmo evento incrementa `receivedCount` e atualiza `lastReceivedAt`, sem duplicar o registro.
* O `payload` armazena o corpo original do provider.
* O webhook referencia recursos externos pelos identificadores presentes no evento (`externalEventId`, etc.).

## Enums

### WebhookStatus

| Valor       | Descrição                                       |
| ----------- | ----------------------------------------------- |
| `RECEIVED`  | Evento recebido, aguardando ou em processamento |
| `PROCESSED` | Evento processado com sucesso                   |
| `FAILED`    | Falha no processamento                          |

### WebhookActionType

| Valor                 | Descrição                     |
| --------------------- | ----------------------------- |
| `UPDATE_PAYMENT`      | Atualização de pagamento      |
| `PAYMENT_PAID`        | Pagamento confirmado          |
| `UPDATE_ORDER`        | Atualização de pedido         |
| `UPDATE_TRANSFER`     | Atualização de transferência  |
| `UPDATE_BANK_ACCOUNT` | Atualização de conta bancária |

## Example

```json theme={null}
{
  "webhookId": "0197a819-3200-7970-ad0c-65ec4c4bf12b",
  "externalProvider": "billing_interface",
  "externalEventId": "evt_4d8b1f20",
  "externalEventType": "PAYMENT_CONFIRMED",
  "actionType": "PAYMENT_PAID",
  "payload": {
    "event": "PAYMENT_CONFIRMED",
    "payment": {
      "id": "pay_4a817c90",
      "status": "CONFIRMED",
      "value": 11400
    }
  },
  "error": null,
  "status": "PROCESSED",
  "receivedCount": 1,
  "lastReceivedAt": "2026-07-03T16:02:10.000Z",
  "processedAt": "2026-07-03T16:02:12.000Z",
  "createdBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "createdAt": "2026-07-03T16:02:10.000Z",
  "updatedBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "updatedAt": "2026-07-03T16:02:12.000Z"
}
```