How govuk-pay/pay-webhooks works
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: WebhookMessageService.java Message service · WebhookService.java Webhook service · WebhookResource.java Webhook API · WebhookMessagePollingService.java Queue polling
Components 18
Event ingestion
- Event handler
src/main/java/uk/gov/pay/webhooks/queue/EventMessageHandler.java - Message service
src/main/java/uk/gov/pay/webhooks/message/WebhookMessageService.java - Ledger service
src/main/java/uk/gov/pay/webhooks/ledger/LedgerService.java
Webhook management
- Webhook API
src/main/java/uk/gov/pay/webhooks/webhook/resource/WebhookResource.java - Request validation
src/main/java/uk/gov/pay/webhooks/validations/WebhookRequestValidator.java - Callback URL checks
src/main/java/uk/gov/pay/webhooks/validations/CallbackUrlService.java - Webhook service
src/main/java/uk/gov/pay/webhooks/webhook/WebhookService.java - Service configuration
src/main/java/uk/gov/pay/webhooks/app/WebhooksConfig.java
Message delivery
- Queue polling
src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/WebhookMessagePollingService.java - Send attempter
src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/SendAttempter.java - HTTP message sender
src/main/java/uk/gov/pay/webhooks/message/WebhookMessageSender.java
Persistence
- Webhook records
src/main/java/uk/gov/pay/webhooks/webhook/dao/entity/WebhookEntity.java - Message records
src/main/java/uk/gov/pay/webhooks/message/dao/entity/WebhookMessageEntity.java - Delivery queue records
src/main/java/uk/gov/pay/webhooks/deliveryqueue/dao/WebhookDeliveryQueueEntity.java - Event types
src/main/java/uk/gov/pay/webhooks/eventtype/dao/EventTypeEntity.java
Other components
- Payment events
- API client
- Partner callback
Connections 17
- Payment events → Event handler: supplies events
- Event handler → Message service: dispatches to
src/main/java/uk/gov/pay/webhooks/queue/EventMessageHandler.java - Message service → Webhook service: finds subscribers
src/main/java/uk/gov/pay/webhooks/message/WebhookMessageService.java - Message service → Ledger service: loads transaction
src/main/java/uk/gov/pay/webhooks/message/WebhookMessageService.java - Message service → Message records: creates messages
src/main/java/uk/gov/pay/webhooks/message/WebhookMessageService.java - Message service → Delivery queue records: enqueues delivery
src/main/java/uk/gov/pay/webhooks/message/WebhookMessageService.java - API client → Webhook API: calls API
README.md - Webhook API → Request validation: validates requests
src/main/java/uk/gov/pay/webhooks/webhook/resource/WebhookResource.java - Webhook API → Webhook service: delegates operations
src/main/java/uk/gov/pay/webhooks/webhook/resource/WebhookResource.java - Webhook service → Webhook records: manages webhooks
src/main/java/uk/gov/pay/webhooks/webhook/WebhookService.java - Webhook service → Event types: looks up subscriptions
src/main/java/uk/gov/pay/webhooks/webhook/WebhookService.java - Request validation → Callback URL checks: checks callback URL
src/main/java/uk/gov/pay/webhooks/validations/WebhookRequestValidator.java - Callback URL checks → Service configuration: reads allowlist
src/main/java/uk/gov/pay/webhooks/validations/CallbackUrlService.java - Queue polling → Send attempter: delegates attempts
src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/WebhookMessagePollingService.java - Queue polling → Delivery queue records: selects pending work
src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/WebhookMessagePollingService.java - Send attempter → HTTP message sender: invokes sender
src/main/java/uk/gov/pay/webhooks/deliveryqueue/managed/SendAttempter.java - HTTP message sender → Partner callback: posts webhook
README.md