# govuk-pay/pay-webhooks architecture

> Architecture diagram of the GitHub repository govuk-pay/pay-webhooks, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/govuk-pay/pay-webhooks
- Repository: https://github.com/govuk-pay/pay-webhooks

## Overview

pay-webhooks is a GOV.UK Pay service that manages partner webhook subscriptions and delivers matching payment events to their callback URLs. The main flow is inbound event handling, subscription matching and message creation, then queued delivery; the API also supports webhook management and delivery-history queries. The graph reflects relationships shown in the README or SOURCE INDEX references. Several delivery and API details are unsampled, so those links are omitted rather than inferred.

Main entry points: [`src/main/java/uk/gov/pay/webhooks/message/WebhookMessageService.java`](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/message/WebhookMessageService.java) (Message service), [`src/main/java/uk/gov/pay/webhooks/webhook/WebhookService.java`](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/webhook/WebhookService.java) (Webhook service), [`src/main/java/uk/gov/pay/webhooks/webhook/resource/WebhookResource.java`](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/webhook/resource/WebhookResource.java) (Webhook API), [`src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/WebhookMessagePollingService.java`](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/WebhookMessagePollingService.java) (Queue polling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Event ingestion"]
  node_queue_handler["Event handler"]
  node_message_service["Message service"]
  node_ledger["Ledger service<br/>[LedgerService.java]"]
end

subgraph group_management["Webhook management"]
  node_webhook_resource["Webhook API"]
  node_validator["Request validation"]
  node_callback_validation["Callback URL checks"]
  node_webhook_service["Webhook service"]
  node_config["Service configuration"]
end

subgraph group_delivery["Message delivery"]
  node_polling["Queue polling"]
  node_send_attempter["Send attempter<br/>[SendAttempter.java]"]
  node_sender["HTTP message sender"]
end

subgraph group_data["Persistence"]
  node_webhook_store[("Webhook records<br/>[WebhookEntity.java]")]
  node_message_store[("Message records")]
  node_delivery_store[("Delivery queue records")]
  node_event_types[("Event types")]
end

node_event_source(("Payment events"))
node_api_user(("API client"))
node_callback(("Partner callback"))

node_event_source -.->|"supplies events"| node_queue_handler
node_queue_handler -->|"dispatches to"| node_message_service
node_message_service -->|"finds subscribers"| node_webhook_service
node_message_service -->|"loads transaction"| node_ledger
node_message_service -->|"creates messages"| node_message_store
node_message_service -->|"enqueues delivery"| node_delivery_store
node_api_user -->|"calls API"| node_webhook_resource
node_webhook_resource -->|"validates requests"| node_validator
node_webhook_resource -->|"delegates operations"| node_webhook_service
node_webhook_service -->|"manages webhooks"| node_webhook_store
node_webhook_service -->|"looks up subscriptions"| node_event_types
node_validator -.->|"checks callback URL"| node_callback_validation
node_callback_validation -->|"reads allowlist"| node_config
node_polling -->|"delegates attempts"| node_send_attempter
node_polling -->|"selects pending work"| node_delivery_store
node_send_attempter -.->|"invokes sender"| node_sender
node_sender -.->|"posts webhook"| node_callback

click node_queue_handler "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/queue/EventMessageHandler.java"
click node_message_service "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/message/WebhookMessageService.java"
click node_ledger "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/ledger/LedgerService.java"
click node_webhook_resource "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/webhook/resource/WebhookResource.java"
click node_validator "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/validations/WebhookRequestValidator.java"
click node_callback_validation "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/validations/CallbackUrlService.java"
click node_webhook_service "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/webhook/WebhookService.java"
click node_polling "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/WebhookMessagePollingService.java"
click node_send_attempter "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/SendAttempter.java"
click node_sender "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/message/WebhookMessageSender.java"
click node_webhook_store "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/webhook/dao/entity/WebhookEntity.java"
click node_message_store "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/message/dao/entity/WebhookMessageEntity.java"
click node_delivery_store "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/deliveryqueue/dao/WebhookDeliveryQueueEntity.java"
click node_event_types "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/eventtype/dao/EventTypeEntity.java"
click node_config "https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/app/WebhooksConfig.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_queue_handler,node_message_service,node_ledger,node_api_user toneBlue
class node_webhook_resource,node_validator,node_callback_validation,node_webhook_service,node_config toneAmber
class node_polling,node_send_attempter,node_sender toneMint
class node_webhook_store,node_message_store,node_delivery_store,node_event_types toneRose
class node_event_source,node_callback toneIndigo
```

## Components

### Event ingestion

- [Event handler](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/queue/EventMessageHandler.java): `src/main/java/uk/gov/pay/webhooks/queue/EventMessageHandler.java`
- [Message service](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/message/WebhookMessageService.java): `src/main/java/uk/gov/pay/webhooks/message/WebhookMessageService.java`
- [Ledger service](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/ledger/LedgerService.java): `src/main/java/uk/gov/pay/webhooks/ledger/LedgerService.java`

### Webhook management

- [Webhook API](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/webhook/resource/WebhookResource.java): `src/main/java/uk/gov/pay/webhooks/webhook/resource/WebhookResource.java`
- [Request validation](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/validations/WebhookRequestValidator.java): `src/main/java/uk/gov/pay/webhooks/validations/WebhookRequestValidator.java`
- [Callback URL checks](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/validations/CallbackUrlService.java): `src/main/java/uk/gov/pay/webhooks/validations/CallbackUrlService.java`
- [Webhook service](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/webhook/WebhookService.java): `src/main/java/uk/gov/pay/webhooks/webhook/WebhookService.java`
- [Service configuration](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/app/WebhooksConfig.java): `src/main/java/uk/gov/pay/webhooks/app/WebhooksConfig.java`

### Message delivery

- [Queue polling](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/WebhookMessagePollingService.java): `src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/WebhookMessagePollingService.java`
- [Send attempter](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/SendAttempter.java): `src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/SendAttempter.java`
- [HTTP message sender](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/message/WebhookMessageSender.java): `src/main/java/uk/gov/pay/webhooks/message/WebhookMessageSender.java`

### Persistence

- [Webhook records](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/webhook/dao/entity/WebhookEntity.java): `src/main/java/uk/gov/pay/webhooks/webhook/dao/entity/WebhookEntity.java`
- [Message records](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/message/dao/entity/WebhookMessageEntity.java): `src/main/java/uk/gov/pay/webhooks/message/dao/entity/WebhookMessageEntity.java`
- [Delivery queue records](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/deliveryqueue/dao/WebhookDeliveryQueueEntity.java): `src/main/java/uk/gov/pay/webhooks/deliveryqueue/dao/WebhookDeliveryQueueEntity.java`
- [Event types](https://github.com/govuk-pay/pay-webhooks/blob/main/src/main/java/uk/gov/pay/webhooks/eventtype/dao/EventTypeEntity.java): `src/main/java/uk/gov/pay/webhooks/eventtype/dao/EventTypeEntity.java`

### Other components

- **Payment events**
- **API client**
- **Partner callback**

## Connections

- Payment events → Event handler: supplies events
- Event handler → Message service: dispatches to (evidence: `src/main/java/uk/gov/pay/webhooks/queue/EventMessageHandler.java`)
- Message service → Webhook service: finds subscribers (evidence: `src/main/java/uk/gov/pay/webhooks/message/WebhookMessageService.java`)
- Message service → Ledger service: loads transaction (evidence: `src/main/java/uk/gov/pay/webhooks/message/WebhookMessageService.java`)
- Message service → Message records: creates messages (evidence: `src/main/java/uk/gov/pay/webhooks/message/WebhookMessageService.java`)
- Message service → Delivery queue records: enqueues delivery (evidence: `src/main/java/uk/gov/pay/webhooks/message/WebhookMessageService.java`)
- API client → Webhook API: calls API (evidence: `README.md`)
- Webhook API → Request validation: validates requests (evidence: `src/main/java/uk/gov/pay/webhooks/webhook/resource/WebhookResource.java`)
- Webhook API → Webhook service: delegates operations (evidence: `src/main/java/uk/gov/pay/webhooks/webhook/resource/WebhookResource.java`)
- Webhook service → Webhook records: manages webhooks (evidence: `src/main/java/uk/gov/pay/webhooks/webhook/WebhookService.java`)
- Webhook service → Event types: looks up subscriptions (evidence: `src/main/java/uk/gov/pay/webhooks/webhook/WebhookService.java`)
- Request validation → Callback URL checks: checks callback URL (evidence: `src/main/java/uk/gov/pay/webhooks/validations/WebhookRequestValidator.java`)
- Callback URL checks → Service configuration: reads allowlist (evidence: `src/main/java/uk/gov/pay/webhooks/validations/CallbackUrlService.java`)
- Queue polling → Send attempter: delegates attempts (evidence: `src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/WebhookMessagePollingService.java`)
- Queue polling → Delivery queue records: selects pending work (evidence: `src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/WebhookMessagePollingService.java`)
- Send attempter → HTTP message sender: invokes sender (evidence: `src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/SendAttempter.java`)
- HTTP message sender → Partner callback: posts webhook (evidence: `README.md`)
