Cross-region messaging
Set up channels that span multiple npayload instances for global applications
Cross-region messaging lets a channel span multiple npayload instances in different regions. Messages published in one region are automatically delivered to subscribers in other regions, with guaranteed delivery and ordering.
When to use cross-region
- Global applications where users and services are distributed across continents
- Disaster recovery with active-active or active-passive replication
- Data residency compliance where processing must happen in specific regions
- Low-latency delivery to subscribers near each region
Enable cross-region on a channel
const channel = await npayload.channels.create({
name: 'global-events',
description: 'Events replicated across US and EU',
crossRegion: {
enabled: true,
replicationMode: 'active-active',
regions: ['us-east-1', 'eu-west-1'],
},
});Replication modes
| Mode | Description | Use case |
|---|---|---|
| Active-active | Publish and subscribe in any region. Messages flow both ways. | Global apps, lowest latency |
| Active-passive | Publish in primary region. Subscribers in secondary receive replicas. | Disaster recovery, read replicas |
// Active-passive: publish in US, replicate to EU
await npayload.channels.create({
name: 'us-primary-events',
crossRegion: {
enabled: true,
replicationMode: 'active-passive',
primaryRegion: 'us-east-1',
replicaRegions: ['eu-west-1', 'ap-southeast-1'],
},
});Data residency controls
Cross-region messaging requires explicit consent for data to leave its origin region. This is enforced at the organization level.
// Grant consent for data to flow between regions
await npayload.organizations.grantDataResidencyConsent({
sourceRegion: 'eu-west-1',
targetRegion: 'us-east-1',
channels: ['global-events'],
purpose: 'Cross-region replication for global service delivery',
});Without explicit data residency consent, messages will not be replicated to other regions. This is a compliance safeguard. Consent can be revoked at any time, which stops future replication but does not delete already-replicated messages.
Publishing across regions
Once cross-region is enabled, publish normally. npayload handles replication automatically.
// Publish in US East - automatically replicated to EU West
const message = await npayload.messages.publish({
channel: 'global-events',
payload: {
event: 'user.signup',
userId: 'usr_789',
region: 'us-east-1',
},
});The message is stored in the origin region first, then transmitted to all configured replica regions. Subscribers in each region receive the message from their local instance.
Subscribing in a remote region
Subscribers in any enabled region receive messages locally with no additional configuration:
// Subscription in EU West receives messages published in US East
await npayload.subscriptions.create({
channel: 'global-events',
name: 'eu-order-processor',
type: 'webhook',
endpoint: {
url: 'https://eu.myapp.com/webhooks/events',
},
});Ordering guarantees
- Within a region: Messages are delivered in publish order
- Across regions: Messages are delivered in publish order per partition key. Without a partition key, ordering is best-effort across regions
- Transmission latency: Cross-region delivery adds 50 to 200ms depending on distance
// Use partition key for strict ordering across regions
await npayload.messages.publish({
channel: 'global-events',
partitionKey: 'user_789', // All messages for this user delivered in order
payload: { event: 'order.created', orderId: 'ord_001' },
});Monitoring cross-region health
const health = await npayload.channels.getCrossRegionHealth('global-events');
for (const link of health.links) {
console.log(`${link.source} -> ${link.target}: ${link.status}`);
console.log(` Lag: ${link.lagMs}ms, Pending: ${link.pendingMessages}`);
}| Status | Description |
|---|---|
| healthy | Replication is current, lag within normal range |
| lagging | Replication is behind, messages are queued |
| degraded | Connectivity issues, messages will be delivered when connection restores |
Cross-region messaging uses a transmission queue with guaranteed delivery. If connectivity between regions is interrupted, messages queue in the origin region and are delivered when the connection restores. No messages are lost.
Next steps
- Cross-region concepts for architecture details
- Regions and availability for available regions
- Channels guide for channel configuration
Was this page helpful?