Loading...
Loading...
Bi-weekly engineering deep dives on auth, notifications, and developer infrastructure. No spam.
Sign Up for UpdatesPublished by Zyphr
5 min read
Read more
4 min read
Read more
7 min read
Read more
It starts with a 2:00 AM incident report. A high-value customer is trying to log into your dashboard to stop a bleeding production issue, but they can’t get past the multi-factor authentication (MFA) screen. Your internal logs show a 202 Accepted from your push notification provider. In your database, the message is marked as "Sent." But for the user, the screen remains blank. The downstream provider is experiencing a regional outage, and because your code treats "accepted by API" as "delivered to user," you’re effectively flying blind.
This is the "Silent Failure" problem. Relying on a single channel—or a single provider within that channel—creates a single point of failure for your entire user experience. When you're building a platform architecture for SaaS, "Sent" is a vanity metric. The only metric that matters is "Received." To fix this, you need a multi-channel delivery pipeline that handles state, failures, and latency without manual intervention.
To solve this, we have to move beyond simple, synchronous API calls. You need a resilient engine that assumes every downstream dependency will eventually fail and plans accordingly.
A resilient pipeline isn't just a wrapper around fetch(). It’s a distributed system built on four distinct pillars. If you're building this in-house, you might be tempted to skip the queue and go straight to the delivery call. That’s a mistake you’ll regret the first time you hit a traffic spike.
The ingestion of a message must be decoupled from its delivery. When your application calls the Zyphr SDK, we don't immediately try to talk to AWS SES or Twilio. We persist the intent to a high-throughput queue (backed by a distributed log like Kafka or a managed SQS instance). This ensures 100% durability. Even if the entire messaging provider network goes dark, your application remains responsive and the messages aren't lost—they’re just waiting in a durable state.
This layer shouldn't be the job of your business logic. Your code should simply trigger an "Event." The routing layer then looks up the subscriber's preferences, checks their active sessions, and determines the optimal path based on the priority you've assigned. This separation of concerns allows product managers to update notification logic in a dashboard without requiring a developer to push new code to production.
The execution layer manages the actual handshakes with providers. This is where the complexity of provider-specific payloads, retry logic, and secret management lives. Each provider has different quirks: one might require a specific JSON schema for buttons, while another expects a flat key-value map for template variables.
The feedback loop is the most neglected part of the stack. You need real-time telemetry on whether a message was delivered, opened, or clicked. Without this, you can’t trigger the failover logic that makes a pipeline resilient.
Here is how a typical multi-channel request looks in the Zyphr ecosystem:
{
"subscriberId": "user_88291",
"event": "critical-system-alert",
"priority": "high",
"channels": {
"push": { "enabled": true, "ttl": 60 },
"sms": { "enabled": true, "fallback": true },
"email": { "enabled": true }
},
"data": {
"node_id": "us-east-1-db-01",
"issue": "CPU Latency Spike"
}
}
This JSON payload defines a hierarchy. It tells the pipeline: "Try push first. If that doesn't work within 60 seconds, escalate."
A fallback chain is a stateful workflow. It’s not just about sending three messages at once—that’s just spamming your users. It’s about escalating through delivery features based on verifiable feedback.
Consider the "Wait-and-Verify" pattern. For an MFA code, you want the fastest channel first: Push. But if the user's device is offline or the provider is lagging, you can't just wait indefinitely.
Zyphr simplifies this by mapping a single event to multiple variants. You don't write the if/else logic or the timer functions. You define the template variants, and the SDK handles the state machine. Managing this state at scale is difficult—handling millions of concurrent "wait" timers requires a distributed scheduler. Using a simple setTimeout in a Node.js process will result in lost states during a pod restart or deployment.
There is a critical difference between Channel Fallback (moving from Push to SMS) and Provider Failover (moving from one SMS provider to another).
If you're using AWS SES in us-east-1 and that region goes down, your email channel is dead regardless of your fallback logic—unless you have provider failover. A resilient pipeline implements "Circuit Breakers." If your primary provider returns a 500-series error or if latency spikes above a predefined threshold (say, 2500ms for five consecutive requests), the circuit trips.
Traffic is then automatically re-routed to a secondary provider or a different region. Zyphr’s infrastructure monitors these health signals in real-time. We don't wait for you to report an issue; our internal load balancers shift traffic the moment a provider's heartbeat falters.
This level of health monitoring prevents your application from "screaming into the void." It also ensures state consistency—a message retried on a secondary provider should never result in a duplicate delivery if the primary provider suddenly wakes up and processes its backlog.
import { Zyphr } from '@zyphr/sdk';
const zyphr = new Zyphr(process.env.ZYPHR_API_KEY);
// Triggering a delivery with an aggressive fallback strategy
await zyphr.events.trigger({
subscriberId: 'user_456',
eventName: 'security-alert',
metadata: {
ip_address: '192.168.1.1',
location: 'Dublin, IE'
},
options: {
providerStrategy: 'aggressive-failover',
maxRetries: 5
}
});
Every developer has experienced the "Thundering Herd." Maybe it’s a flash sale, a system-wide maintenance alert, or a sudden price movement. You hit your messaging API with 50,000 requests in a single second.
If you’re talking directly to a provider like Twilio or SendGrid, you’ll likely hit their rate limits and receive a 429 error. If your code isn't prepared to handle that with a retry mechanism, those messages are gone. We use a combination of "Token Bucket" and "Leaky Bucket" algorithms to pace outbound traffic.
The real secret to reliable delivery isn't just slowing down—it's prioritization. In a traffic surge, your marketing newsletter should never delay an MFA code or a password reset.
Zyphr’s queue is multi-tenant and priority-aware. High-priority "Transactional" messages jump to the front of the line, while "Bulk" messages are throttled to stay within provider limits. When a provider returns a 429, we implement exponential backoff with jitter. This ensures we don't contribute to the provider's instability while still ensuring your message reaches its destination.
In a distributed pipeline, retries are inevitable. However, retries introduce the risk of duplicate messages. Imagine a scenario where the SMS provider processes the message and sends it to the user's phone, but the network connection drops before they can send the 200 OK back to your server. Your pipeline sees a timeout and retries. Now the user has two MFA codes.
To solve this, we implement idempotency keys at every stage. When your application sends an event, you can include a unique idempotencyKey. Our pipeline stores this key for 24 hours. If we receive a second request with the same key, we return the cached response of the first request instead of initiating a new delivery flow. This protection extends to our internal retries with downstream providers, ensuring that even if a provider is flaky, your user doesn't get spammed.
The biggest problem with the "best-of-breed" approach (using multiple vendors for different channels) is the lack of a unified timeline. When a user says "I didn't get the alert," you have to check the logs of your Auth provider, then your Push provider, then your SMS gateway. It’s a forensic nightmare.
A unified pipeline gives you a single source of truth. You need to see the entire journey of a single message:
Key metrics like Mean Time to Delivery (MTTD) and provider latency distributions should be visible at a glance. If your SMS delivery time suddenly jumps from 5 seconds to 30 seconds, you need to know before your users start complaining.
Furthermore, any message that fails all retry attempts should land in a "Dead Letter Queue" (DLQ). A DLQ isn't just a graveyard; it's a debugging tool. It allows your engineering team to inspect the payload, see the specific error code from the final provider, and manually replay the message once the underlying issue is resolved. To keep your own application in sync, we use HMAC-signed webhooks to report these status changes back to you, ensuring the data in your database matches the reality of the user's phone.
When you move to a multi-channel pipeline, you're often passing sensitive information like email addresses, phone numbers, and notification content. In a SOC2 or GDPR-compliant environment, you can't just log this data in plain text.
Your pipeline must support "Field-Level Encryption." This means sensitive PII is encrypted at the SDK level before it ever reaches the Zyphr ingestion servers. We only decrypt the data at the final moment of delivery to the provider. This ensures that even in the event of a storage breach, your users' data remains protected. We also provide automatic TTLs (Time-To-Live) on message logs, so sensitive notification content is wiped from our systems after a set period, reducing your data surface area.
Building this infrastructure in-house is a common "build vs. buy" trap. On the surface, it’s just a queue and some API calls. In reality, it’s a mountain of maintenance debt. You’ll be responsible for handling provider API version changes, rotating secrets for multiple services, scaling worker pools, and debugging why one specific carrier in Germany is dropping your SMS packets.
If you're an architect or a CTO, your time is better spent on your product's core value proposition, not on becoming an expert in the nuances of APNs delivery receipts or carrier-specific filtering rules.
Next step: Audit your current authentication and alerting flows. Find the single point of failure. If you're only sending an email for password resets and your email provider goes down, your users are locked out.
You can implement your first Push → SMS fallback chain in under 15 minutes. Create a free account at Zyphr and use the @zyphr/sdk to start building a pipeline that handles the 2:00 AM outages for you.