Overview#
An emergency affecting three suburban postal codes needs to reach both local residents who opted in for alerts and the news agencies covering the region, simultaneously, with delivery confirmed and every dispatch action recorded. The Postal Code Alert domain handles that exact workflow: it matches campaign geofences to postal code boundaries, dispatches to verified subscribers and signed news agency webhooks, streams delivery progress in real time, and maintains a full audit trail.
Key Features#
- Geofence-to-postal-code matching with coverage percentage calculation
- Subscriber self-service with OTP verification and rate limiting
- News agency webhook delivery with payload signing, circuit breakers, and retry logic
- Dead letter queue with exponential backoff for failed dispatches
- Real-time SSE dispatch progress streaming with delivery statistics
- Bulk postal code and boundary polygon import
- GDPR-compliant subscriber data export
- Idempotent dispatch with advisory locking to prevent concurrent duplicates
- Per-subscriber frequency capping with configurable daily limits
- Immutable audit logging for all dispatch actions
- Delivery confirmation tracking with callback endpoints
Use Cases#
Relevant sectors include public safety communications, critical infrastructure, and national emergency management.
- Dispatching emergency alerts to residents within geographic zones affected by incidents
- Notifying news agencies of public safety alerts with authenticated webhook delivery
- Managing subscriber opt-in and verification for postal code-based alerting
- Monitoring dispatch progress in real time with delivery success metrics
Integration#
The Postal Code Alert domain connects with geofencing for boundary matching, notification campaigns for recipient management, and public alerts distribution. All queries are scoped by organisation for multi-tenant isolation.
Open Standards#
- GeoJSON (RFC 7946): Postal code boundary polygons and geofence boundaries are stored and exchanged as GeoJSON geometry objects, processed via PostGIS
ST_GeomFromGeoJSONfor spatial intersection and coverage percentage calculations. - W3C Server-Sent Events: Real-time dispatch progress is streamed to clients over HTTP using the
text/event-streammedia type, with keepalive comments and structureddata:lines per the SSE specification. - HMAC-SHA256 (RFC 2104): Outbound webhook payloads are signed and inbound delivery-confirmation callbacks are verified using HMAC-SHA256 signatures carried in the
X-Webhook-Signatureheader, with constant-time digest comparison to prevent timing attacks. - GraphQL: The entire management and dispatch API is exposed as a Strawberry GraphQL schema, with typed queries, mutations, and enums covering subscriber management, dispatch orchestration, and GDPR export.
- ISO 3166-1: Two- and three-character country codes are used throughout to scope postal code validation, normalisation, and geospatial matching to the correct national format per tenant.
- GDPR (EU Regulation 2016/679): A dedicated subscriber data-export mutation is provided to fulfil data-portability obligations under Article 20, and subscriber records include explicit opt-in verification and unsubscribe tokens.
- OAuth 2.0 Bearer Token (RFC 6750): Authenticated GraphQL operations require a valid Bearer token resolved from the request context, with organisation-scoped authorisation enforced on all mutations.
Last Reviewed: 2026-02-24 Last Updated: 2026-04-14