Webhooks: coming soon
Webhooks let CaptainDNS push events to your systems in real time, without having to poll the API. They are under development for V2 of the public API and are not yet available in production. This page explains the plan and the alternatives to use in the meantime.
Status
- V1 (current): webhooks not available.
- V2 (planned): event emission, HMAC signature, retry with exponential backoff, and a delivery monitoring dashboard.
No firm date has been announced for V2. Progress will be communicated in the changelog and on the CaptainDNS blog.
Planned use cases
Here are the events under consideration for V2:
api_key.rotated: a key has been rotated, the old one enters the grace period. Useful to update your secrets manager automatically.api_key.revoked: a key has been revoked. Useful to immediately pull a compromised integration.api_key.expires_soon: a key is approaching its expiration date (typically T-30 days).usage.threshold_reached: credit consumption crosses a threshold (80 %, 100 %, 120 %).usage.overage_reported: the monthly overage has been successfully billed via Paddle.monitoring.alert: an anomaly is detected on a key (spike ten times the average, 429 storm, etc.).
These events are proposals; the final list will be locked after feedback from V1 users.
Temporary alternatives
Until V2 ships, use one of the following patterns:
Polling via response headers
Every public API response includes X-Credits-Remaining and X-Credits-Limit headers. A daily cron calling a low-cost endpoint is enough to trigger alerts on consumption thresholds.
You can also check your usage in the CaptainDNS dashboard (Account > API usage).
Client-side monitoring
In your client, watch the X-Credits-Remaining and X-RateLimit-Remaining response headers. If either drops under a critical threshold, trigger a homemade alert.
Scheduled canary
Run a scheduled job that calls a cheap endpoint (for example POST /public/v1/resolve on a canary domain) and logs the status and headers. A sequence of unexpected 401/403 points to a problem, and the X-Credits-Remaining metric serves as an early signal for plan upgrades.
What V2 will bring
When webhooks ship, you will be able to:
- Register an HTTPS endpoint in the
/account/webhooksdashboard. - Pick events via a set of checkboxes.
- Define a shared secret to verify the HMAC signature of each delivery.
- Consult the delivery dashboard with successes, failures and retry queue.
- Manually replay a failed delivery from the dashboard.
The Starter plan should include 3 endpoints, Pro 10, Business and Enterprise unlimited (subject to a fair-use policy).
Stay informed
To be notified when webhooks launch:
- Subscribe to the CaptainDNS blog: major feature launches are announced in dedicated posts.
- Watch the public API changelog, updated on every release.
- Enterprise customers with an account manager will receive a pre-announcement by email, with the option to test the beta.
In the meantime, the quickstart and the OpenAPI reference remain the best entry points to integrate today.