Watchdogs
A dead-man's switch per webhook stream: expect a matching capture at least every N with G of grace, and alarm through your alert channels when the window passes in silence.
Everything else in WebhookVault answers questions about webhooks that arrived. A watchdog answers the one about webhooks that did not.
That failure has no error to catch. The sender stops, nothing throws, no status code turns red, and you find out when someone tells you their payment never landed. A watchdog is the alarm for exactly that.
What a watchdog is
A matching capture arrives on this endpoint at least every N, with G of grace.
- Interval is how long may pass between matching captures before the stream is late.
- Grace is the jitter you are willing to tolerate before it is a problem. A daily payout that usually lands at 02:00 does not need paging at 02:01.
- Match is optional criteria a capture must satisfy to count, in the same grammar transformations use. Without it, every capture counts.
Miss interval plus grace and the watchdog alarms. A matching capture while it is alarmed recovers it, and both go out through your alert channels as the same incident.
It starts from the history it already holds
A watchdog does not start blind. On creation it reads the endpoint's existing history, so a stream that has been healthy for a month is healthy from the first second rather than after the first interval.
That also means GET /api/v1/watchdogs/suggest can propose an interval from what the endpoint
genuinely receives, instead of asking you to guess:
curl "https://app.webhookvault.net/api/v1/watchdogs/suggest?endpointId=$ENDPOINT" \
-H "Authorization: Bearer $WV_API_KEY"available: false means there is too little history to propose anything, and reason says so
in words you can show someone.
States
| State | Meaning |
|---|---|
waiting | Armed, nothing matching seen yet |
ok | The last matching capture is inside the window |
overdue | Past the interval, inside grace. Silent by design |
alarmed | Past interval plus grace. One alert sent; stays until traffic returns |
recovered | Traffic returned while alarmed. One alert sent; back to ok after one interval |
paused | Switched off. Still fed by captures, never evaluated, never alerts |
plan | Kept, but over your plan's watchdog limit, so not being evaluated |
plan is worth watching for. A watchdog in that state looks configured and is not protecting
anything.
Through the API
curl https://app.webhookvault.net/api/v1/watchdogs \
-H "Authorization: Bearer $WV_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"endpointId": "'"$ENDPOINT"'",
"name": "Daily payout",
"match": { "all": [ { "path": "body.type", "op": "equals", "value": "payout.paid" } ] },
"expectedIntervalSeconds": 86400,
"graceSeconds": 3600
}'Pausing for a planned outage, rather than deleting and rebuilding:
curl -X POST https://app.webhookvault.net/api/v1/watchdogs/{id}/active \
-H "Authorization: Bearer $WV_API_KEY" \
-H "Content-Type: application/json" \
-d '{"active": false}'GET /api/v1/watchdogs/labels?endpointId=… lists the event labels an endpoint has actually
sent, with counts, which is the easiest way to build a match that will genuinely fire.
Plans
Watchdogs start on Solo. Alerts reach your technical contacts by email on every plan; the other destinations are covered in Alerts.
The full reference is under Watchdogs in the API reference.
Deliveries
Every forward attempt with exactly what left the vault and exactly what came back: method, URL, headers and body both ways, status, timing, and what the transformation rules did.
Alerts
Where problems reach you: email on every plan, plus Slack, Discord, Teams, PagerDuty, Opsgenie, incident.io, Datadog, New Relic, Prometheus, Telegram and your own signed webhook.