Gracefully Handling SAML Certificate Expiration with WorkOS Webhooks

SAML certificate expiration often happens silently—by the time users can't log in, it's already too late. WorkOS offers a more proactive approach: sending events before certificates expire, giving teams a chance to act ahead of time.

Why SAML Certificate Expiration Is Easy to Overlook

SAML certificates typically have long validity periods and receive little active attention after deployment. Certificate rotation involves configuration updates on both the identity provider (IdP) and service provider (SP) sides—a cumbersome process that's easy to miss. Once a certificate expires, all SSO logins relying on it fail, directly impacting end users.

The root cause isn't technical difficulty—it's the lack of a reminder mechanism. If certificate expiration dates never make it onto anyone's to-do list, no one will follow up.

SAML (Security Assertion Markup Language) is an XML-based open standard for exchanging authentication and authorization data between identity providers (IdPs) and service providers (SPs). In SSO scenarios, the IdP signs SAML assertions using a private key, and the SP verifies signatures using a pre-configured IdP certificate (typically containing the public key). The certificate is therefore the foundation of the trust chain. Once it expires, signature verification fails, and all SSO login flows relying on that certificate break immediately. Unlike API keys, SAML certificates are typically rotated annually or even less frequently, and rotation requires both parties to coordinate metadata updates—increasing operational complexity and making expiration risks more insidious.

WorkOS's Advance Warning Mechanism

WorkOS's approach is to proactively push an event when a certificate nears expiration. This event contains relevant certificate information, allowing the recipient to determine what action to take.

The key point is that this event isn't just a simple notification—it's a trigger that can be translated into concrete workflows. The core idea from the original article is: turn each certificate's expiration warning into an open reminder item and route it to the person actually capable of completing the renewal.

This is far more effective than mass emails or posting to public channels. Broadcast notifications easily get buried, while reminders directed at specific owners actually drive action.

A webhook is an HTTP callback-based event notification mechanism. When a specific event occurs, the source system sends a POST request to a pre-configured URL carrying event data. Compared to polling APIs, webhooks provide near-real-time push, reducing latency and resource consumption. In WorkOS's SAML certificate expiration scenario, webhook events allow recipients to be notified before a certificate becomes invalid and to trigger automated workflows (such as creating tickets or sending targeted reminders). Recipients need to ensure endpoint reliability, handle idempotency, and verify request origins (e.g., via signatures) to prevent misuse or replay attacks.

Turning Events into Actionable Workflows

Determine Routing Targets

A reminder without a clear owner is no reminder at all. Teams need to clarify in advance: which IdP's certificate is whose responsibility to renew? This could be IT operations, the security team, or a specific application owner.

Establish Deduplication and Tracking

Each certificate should correspond to a single independent reminder, rather than creating a new one for every event. This avoids noise from duplicate notifications and enables clear tracking of each reminder's status.

Idempotency means that performing the same operation multiple times produces the same result as performing it once. In webhook processing, the same certificate expiration event may be received multiple times due to network retries or duplicate event delivery. If a new reminder is created for every event, this leads to notification overload and tracking chaos. Implementing idempotent handling typically requires using a unique identifier for each certificate (such as a certificate ID or fingerprint) as a deduplication key, ensuring each certificate corresponds to exactly one open reminder. This avoids duplicate noise while accurately tracking each certificate's status through to closure.

Closed-Loop Verification

Once certificate renewal is complete, the reminder should be closed. At the same time, you need to verify that the new certificate is actually in effect, avoiding situations where you "think it's renewed but it isn't."

Common Pitfalls

Treating webhook events as log records is a waste. The value of events lies in triggering action, not archiving. Another pitfall is over-reliance on email notifications—emails are easily ignored and don't allow tracking of progress.

Conclusion

SAML certificate expiration is an operational incident that can be completely avoided. WorkOS's webhook events provide a window for early intervention, but the real value depends on how teams translate this signal into workflows with clear ownership, tracking, and closure. The technical solution is only the starting point—process design is what matters.