Skip to main content

​
Campos

CampoTipoDescrição
webhookIdUUIDIdentificador único
externalProviderStringNome do provider externo
externalEventIdStringID do evento no provider
externalEventTypeStringTipo do evento no provider
actionTypeWebhookActionTypeAção derivada do evento
payloadJsonConteúdo original do provider
errorString?Mensagem de erro do processamento
statusWebhookStatusStatus de processamento
receivedCountIntNúmero de entregas do provider para o mesmo evento
lastReceivedAtDateTimeData da última entrega
processedAtDateTime?Data do processamento bem-sucedido
createdByUUID?Usuário que criou o registro, quando aplicável
createdAtDateTimeData de criação
updatedByUUID?Usuário que fez a última atualização, quando aplicável
updatedAtDateTimeData 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

ValorDescrição
RECEIVEDEvento recebido, aguardando ou em processamento
PROCESSEDEvento processado com sucesso
FAILEDFalha no processamento

​
WebhookActionType

ValorDescrição
UPDATE_PAYMENTAtualização de pagamento
PAYMENT_PAIDPagamento confirmado
UPDATE_ORDERAtualização de pedido
UPDATE_TRANSFERAtualização de transferência
UPDATE_BANK_ACCOUNTAtualização de conta bancária

​
Example

{
  "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"
}