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.
Base URL
Section titled “Base URL”https://my.gridwatchdog.comAll endpoints below are relative to this base URL.
Getting a token
Section titled “Getting a token”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_hereWebhook object
Section titled “Webhook object”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.
Events
Section titled “Events”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.
Mute, filtered mode and an ended plan
Section titled “Mute, filtered mode and an ended plan”- Muting a device quiets its email only.
power_lostandpower_restoredstill fire while it is muted. The checks behindlost_contactandno_signaldon’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_lostandpower_restoredfires 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.
Webhook types
Section titled “Webhook types”| 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.
Endpoints
Section titled “Endpoints”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).
List webhooks
Section titled “List webhooks”GET /account/webhooksReturns all your webhooks.
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 } ]}Create a webhook
Section titled “Create a webhook”POST /account/webhooksSend 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. |
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": … }.
Edit a webhook
Section titled “Edit a webhook”POST /account/webhooks/:idUpdate 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.
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 }Delete a webhook
Section titled “Delete a webhook”POST /account/webhooks/:id/deletecurl -X POST https://my.gridwatchdog.com/account/webhooks/13/delete \ -H "Authorization: Bearer gwk_your_token_here"{ "ok": true }Re-enable a webhook
Section titled “Re-enable a webhook”POST /account/webhooks/:id/enableRe-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.
curl -X POST https://my.gridwatchdog.com/account/webhooks/13/enable \ -H "Authorization: Bearer gwk_your_token_here"{ "ok": true }Send a test delivery
Section titled “Send a test delivery”POST /account/webhooks/:id/testFires 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.
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).
Disable a webhook
Section titled “Disable a webhook”POST /account/webhooks/:id/disableSwitches a webhook off without deleting it. Turn it back on with Re-enable.
curl -X POST https://my.gridwatchdog.com/account/webhooks/13/disable \ -H "Authorization: Bearer gwk_your_token_here"{ "ok": true }Rotate the signing secret
Section titled “Rotate the signing secret”POST /account/webhooks/:id/rotate-secretGeneric 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.
curl -X POST https://my.gridwatchdog.com/account/webhooks/13/rotate-secret \ -H "Authorization: Bearer gwk_your_token_here"{ "ok": true, "secret": "4f1c…" }Verifying generic deliveries
Section titled “Verifying generic deliveries”For generic webhooks, every delivery we POST to your endpoint carries two
headers:
X-GridWatchdog-Event: the event type, the same asevent_typein 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.
Errors
Section titled “Errors”| 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. |