Skip to content

Webhooks API

The Webhooks API lets you manage your outage webhooks from a script instead of the account dashboard. It does exactly what the Webhooks page in your account does — create, list, edit, delete, and send a test — authenticated with a scoped API token.

A token can only manage webhooks: it can’t change your account or create other tokens. Because it can add a webhook that sends your alerts anywhere, keep it as safe as a password; see Keeping tokens safe.

https://my.gridwatchdog.com

All endpoints below are relative to this base URL.

You need an API token to use this API. Create one on the API tokens page of your account: API tokens explains how to create, rotate and revoke tokens, when they expire, the limits that apply, and what to do if one might have leaked.

Send the token as a bearer token on every request:

Authorization: Bearer gwk_your_token_here

A webhook is returned as a JSON object with these fields:

Field Type Description
id number The webhook’s unique id.
type string discord, slack, or generic.
url string The endpoint we deliver to.
enabled boolean Whether the webhook is active. Auto-disables after repeated failures.
events array of strings Which events fire this webhook (see Events).
device_scope string or null A device id to scope to one device, or null for all your devices.
last_status string or null The outcome of the most recent delivery attempt.
created_at number Unix timestamp (seconds) when the webhook was created.
secret_rotated_at number or null Unix timestamp (seconds) of the last signing-secret rotation, or null if the secret is the one issued at creation.

The webhook object never includes the signing secret. A generic webhook’s secret is returned once: by the create that issued it, or by the rotate that replaced it.

A webhook fires only on the events in its events list:

Event Meaning
power_lost Mains power was lost.
power_restored Mains power came back.
lost_contact During an outage, the device stopped checking in (the Device Went Dark email).
no_signal A device that wasn’t in an outage alert stopped checking in (the No Signal email).
silence_resolved The device checked in again after a No Signal alert, with its power on (the Back Online email).

If you omit events when creating a webhook, it subscribes to all of them. A webhook created before no_signal existed keeps its own list: add no_signal with an edit to receive it.

  • Muting a device quiets its email only. power_lost and power_restored still fire while it is muted. The checks behind lost_contact and no_signal don’t run during a mute, so those two events don’t happen until the mute ends.
  • Filtered mode holds back the power-out email during a run of flickers. It doesn’t hold back webhooks: every power_lost and power_restored fires straight away.
  • When a device’s service has ended and its 30-day grace period is over, no webhook fires for it until it is renewed. During the grace period they fire as normal.
Type URL requirement
discord An https:// URL on discord.com, discordapp.com, or ptb.discord.com.
slack An https:// URL on hooks.slack.com.
generic Any https:// URL. Deliveries are HMAC-signed (see below).

You can have up to 10 webhooks per account.

Every endpoint requires the Authorization: Bearer … header. A bearer token that is unknown, expired or revoked gets 401 { "error": "invalid_token" }. A request with no Authorization: Bearer header is treated as a browser request instead: a POST gets a plain-text 403 Forbidden, and GET /account/webhooks returns the sign-in page (HTML, status 200).

GET /account/webhooks

Returns all your webhooks.

Terminal window
curl -H "Authorization: Bearer gwk_your_token_here" \
https://my.gridwatchdog.com/account/webhooks
{
"webhooks": [
{
"id": 12,
"type": "discord",
"url": "https://discord.com/api/webhooks/…",
"enabled": true,
"events": ["power_lost", "power_restored"],
"device_scope": null,
"last_status": "ok",
"created_at": 1758666000
}
]
}
POST /account/webhooks

Send the fields as JSON (Content-Type: application/json) or as form-encoded values.

Field Required Description
type yes discord, slack, or generic.
url yes The delivery URL (must satisfy the type’s URL requirement).
events no Array (JSON) or comma-separated string. Defaults to every event.
device_scope no A device id to scope to one device. Omit for all your devices.
Terminal window
curl -X POST https://my.gridwatchdog.com/account/webhooks \
-H "Authorization: Bearer gwk_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"type": "generic",
"url": "https://example.com/hooks/gridwatchdog",
"events": ["power_lost", "power_restored"]
}'
{ "ok": true, "id": 13, "secret": "4f1c…" }

For a generic webhook the reply includes its signing secret. This is the only time we return it, so store it now. A discord or slack webhook has no secret, and its reply is just { "ok": true, "id": … }.

POST /account/webhooks/:id

Update the url, the events, or both. Fields you omit are left unchanged. The new url is re-validated against the webhook’s existing type. The type and device_scope can’t be edited: to change either, delete the webhook and create it again.

Terminal window
curl -X POST https://my.gridwatchdog.com/account/webhooks/13 \
-H "Authorization: Bearer gwk_your_token_here" \
-H "Content-Type: application/json" \
-d '{ "events": ["power_lost", "lost_contact"] }'
{ "ok": true }
POST /account/webhooks/:id/delete
Terminal window
curl -X POST https://my.gridwatchdog.com/account/webhooks/13/delete \
-H "Authorization: Bearer gwk_your_token_here"
{ "ok": true }
POST /account/webhooks/:id/enable

Re-enables a webhook that was switched off, either by you or automatically after 10 failed deliveries in a row. A disabled webhook stays off until this endpoint or a successful test delivery turns it back on: real events don’t re-enable it.

Terminal window
curl -X POST https://my.gridwatchdog.com/account/webhooks/13/enable \
-H "Authorization: Bearer gwk_your_token_here"
{ "ok": true }
POST /account/webhooks/:id/test

Fires a synthetic power_lost delivery to the webhook so you can confirm it’s wired up. A successful test on a disabled webhook re-enables it.

Terminal window
curl -X POST https://my.gridwatchdog.com/account/webhooks/13/test \
-H "Authorization: Bearer gwk_your_token_here"
{ "ok": true, "status": 204, "reenabled": false }

The reply is 200 whether or not the delivery worked. ok says whether your endpoint answered with a 2xx, and status is the HTTP status it returned (0 if it couldn’t be reached).

POST /account/webhooks/:id/disable

Switches a webhook off without deleting it. Turn it back on with Re-enable.

Terminal window
curl -X POST https://my.gridwatchdog.com/account/webhooks/13/disable \
-H "Authorization: Bearer gwk_your_token_here"
{ "ok": true }
POST /account/webhooks/:id/rotate-secret

Generic webhooks only. Replaces the webhook’s signing secret and returns the new one; the id, URL and events stay the same. This reply is the only time the new secret is returned. Every delivery from then on is signed with the new secret, so update your endpoint’s verification. A Discord or Slack webhook has no secret and gets a 400. If you lost a secret, rotating is how you get a new one.

Terminal window
curl -X POST https://my.gridwatchdog.com/account/webhooks/13/rotate-secret \
-H "Authorization: Bearer gwk_your_token_here"
{ "ok": true, "secret": "4f1c…" }

For generic webhooks, every delivery we POST to your endpoint carries two headers:

  • X-GridWatchdog-Event: the event type, the same as event_type in the body, so you can route without parsing the JSON.
  • X-GridWatchdog-Signature: the HMAC-SHA256 of the raw request body, keyed by the webhook’s secret (returned once, when you create the webhook or rotate its secret), hex-encoded.

Recompute the signature on your side and compare to confirm the delivery really came from GridWatchdog. After a secret rotation, only the new secret verifies. Discord and Slack deliveries are not signed — they go only to their respective verified hosts.

Status Body Meaning
401 { "error": "invalid_token" } The bearer token is unknown, revoked, or expired.
403 Forbidden (plain text) No Authorization: Bearer header on a POST (see Endpoints).
400 { "error": "…" } Bad type, an invalid url for the type, no valid events, or a secret rotation on a Discord/Slack webhook.
404 { "error": "Not found" } No webhook with that id belongs to you.
409 { "error": "Too many webhooks" } You’ve reached the 10-webhook limit.