API deprecation is one of the more underappreciated operational risks in software engineering. The code change that removes a deprecated endpoint is typically straightforward — it's the weeks before and after where incidents happen. Consumers who weren't reached by deprecation notices are still calling v1 endpoints that no longer exist. Canary deployments serving v2 traffic have subtle behavioral differences that only surface at scale. Migration cutover windows have unclear success criteria.
Uptime monitoring, usually associated with "is the website up?", is underused as a tool for managing API version lifecycle. This guide covers how to monitor v1 and v2 API endpoints simultaneously during migration, set up deprecation deadline alerting, use webhook notifications for version-specific health events, implement canary monitoring, and validate version-specific responses using keyword monitoring.
The Monitoring Gap During API Migration
Most API teams have monitoring for their current production API. They have far less monitoring for the migration window — specifically the period when:
- v1 endpoints are still live and serving real consumers
- v2 endpoints are being progressively rolled out
- Traffic is split between versions (canary or gradual rollout)
- Deprecation deadlines are approaching
This gap is where incidents happen. A v1 endpoint that starts returning 500s after a shared database schema migration gets caught by nobody because all monitoring attention shifted to v2. A canary deployment serving 10% of v2 traffic has elevated error rates that don't trigger aggregate-level alerts because they're diluted by healthy v1 traffic.
Monitoring v1 and v2 Simultaneously
The first step is treating both endpoints as first-class monitored services for the duration of the migration. This means separate monitors for each version, not a single monitor on the base domain.
Structure your monitors by version:
Monitor: Auth API v1
URL: https://api.yourproduct.com/v1/auth/status
Check interval: 1 minute
Alert: PagerDuty + Slack #api-ops
Monitor: Auth API v2
URL: https://api.yourproduct.com/v2/auth/status
Check interval: 1 minute
Alert: PagerDuty + Slack #api-ops
Monitor: Orders API v1
URL: https://api.yourproduct.com/v1/orders/health
Check interval: 5 minutes
Alert: Slack #api-ops
Monitor: Orders API v2
URL: https://api.yourproduct.com/v2/orders/health
Check interval: 5 minutes
Alert: Slack #api-ops
Using Vigilmon, each monitor is independently configured with its own alert routing, check interval, and keyword validation. Version-specific failures alert on version-specific channels.
Important: Keep v1 monitors active until all consumers have migrated and the deprecation is complete — not just until v2 is launched. The most common mistake is treating v1 monitoring as irrelevant once v2 is live.
Deprecation Deadline Monitoring
Deprecation deadlines are coordination problems as much as technical problems. The engineering work of removing a deprecated endpoint is typically trivial. The challenge is ensuring all consumers have migrated before the deadline, and communicating clearly when the deadline is approaching.
Keyword Monitoring for Deprecation Headers
Most API frameworks support adding deprecation warning headers to responses from deprecated endpoints:
Deprecation: true
Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Link: <https://docs.yourproduct.com/migration>; rel="successor-version"
Vigilmon supports keyword monitoring — checking that a specific string is present or absent in the HTTP response body or headers. Use this to verify:
- Deprecation header is present on v1 endpoints — confirms your framework is correctly serving the deprecation signal to all consumers
- Deprecation header is absent on v2 endpoints — confirms v2 is not inadvertently serving deprecated signals
- Sunset date is correct — if the header value changes unexpectedly (a deployment error modifying the date), your monitor catches it
Monitoring the Sunset Window
Set up a dedicated monitor for the v1 endpoint that you expect to return 410 Gone after the deprecation deadline:
Before deadline: Monitor for HTTP 200 (endpoint must be alive)
After deadline: Monitor for HTTP 410 (endpoint must be retired)
This inverts the normal monitoring logic. After the sunset date, an HTTP 200 from a supposedly retired endpoint is an alert condition — it means the retirement deployment didn't happen or was rolled back without communication.
Webhook Notifications for API Version Health Events
Webhook integrations allow you to build automated workflows around API version health events. When a v1 endpoint starts returning errors during the migration window, your workflow could:
- Notify the API team's Slack channel with version-specific context
- Post to a shared migration tracking document
- Trigger a PagerDuty incident tagged with "v1-migration"
- Send an automated email to known API consumers who haven't migrated yet
Vigilmon's webhook delivery supports custom payloads routed to different endpoints per monitor, allowing you to build version-aware alert pipelines.
Example webhook routing:
- v1 downtime alert → Slack #api-v1-incidents + migration tracking webhook
- v2 downtime alert → Slack #api-v2-incidents + standard PagerDuty
- Sunset date endpoint 200 detection → automated migration deadline escalation
Canary Monitoring During Migration
Canary deployments — where a small percentage of traffic (5%, 10%) is routed to the new version before full rollout — are standard practice for major API changes. But canary monitoring requires care:
Don't monitor only the primary endpoint. If v2 is serving 10% of traffic via a canary header or subdomain, monitor the canary endpoint directly:
Monitor: Auth API v2 Canary
URL: https://api.yourproduct.com/v2/auth/status
Header: X-Canary: true
Check interval: 1 minute
Monitor independently, alert independently. A canary that's returning errors at 30% error rate may not surface in aggregate dashboards if the v1 fleet is healthy. Direct endpoint monitoring catches version-specific failures that aggregate metrics miss.
Use keyword monitoring to validate version routing. If your API returns a version identifier in the response body, monitor for it:
{"version": "2.1.4", "status": "healthy"}
Keyword monitoring verifies that requests to the v2 canary endpoint are actually being served by v2, not routed back to v1 by a misconfigured load balancer rule.
Response Validation for Version-Specific Behavior
Different API versions may return structurally different response schemas. Keyword monitoring catches cases where:
- A v2 endpoint returns a v1-format response body (routing misconfiguration)
- A field required by v2 consumers is missing from the response (regression)
- A deprecated v1 field appears in a v2 response (contract violation)
Configure keyword monitors to validate presence of required v2 fields and absence of deprecated v1 fields:
Monitor: Orders API v2 Schema Validation
URL: https://api.yourproduct.com/v2/orders/health
Keyword present: "orderId" ← required v2 field
Keyword absent: "order_id" ← deprecated v1 field name
This lightweight validation provides continuous contract testing for the migration period without requiring a full integration test suite to run at monitoring frequency.
Practical Checklist: API Version Migration Monitoring
Before migration begins:
- [ ] Create monitors for all v1 endpoints to be deprecated
- [ ] Create monitors for all v2 endpoints being introduced
- [ ] Configure version-specific alert routing (separate Slack channels or PagerDuty services)
- [ ] Set up keyword monitors validating deprecation headers on v1
During migration:
- [ ] Monitor canary endpoints directly
- [ ] Validate v2 response schemas with keyword monitoring
- [ ] Keep v1 monitors active — treat v1 errors as P1 incidents
- [ ] Add response time monitors to catch v2 latency regressions
At deprecation deadline:
- [ ] Invert v1 monitors to alert on HTTP 200 (expect 410)
- [ ] Confirm v1 traffic has dropped to zero in your analytics
- [ ] Keep inverted monitors active for 30 days post-sunset
Vigilmon's free tier supports 5 monitors with keyword matching, multi-region probing, and webhook integrations — enough to cover a focused migration of a small API surface. Paid plans scale to larger endpoint inventories with no configuration complexity added.
API deprecation incidents are almost always avoidable with the right monitoring in place. The engineering investment is low; the cost of a missed incident during migration is high. Treat your deprecated endpoints as the highest-risk services in your infrastructure until the day they're retired.