monitor.result.found, check the signature on every delivery, and answer with a 2xx status. For the body and headers of each event type, see Webhook payload.
You need an API key, a monitor, and an HTTPS endpoint that the public internet can reach. To create a monitor, see Create a monitor.
Subscribe to new results
A monitor with a webhook sendsmonitor.result.found for each new result unless webhook.events leaves it out. Set the webhook in the create request. The create response carries the signing secret, webhook.secret. This request creates a monitor that sends only new results, changed results and the disabled notice to your endpoint:
webhook.url, webhook.events and webhook.secret. Store the secret now, for example as KEENABLE_WEBHOOK_SECRET in your secret manager. Once webhook.events is set, the monitor sends only the types it lists. If you leave webhook.events out, the monitor sends every event type, results included.
To change webhook.url or webhook.events later, send them to Update a monitor. The secret stays the same. If you add a webhook to a monitor that had none, the update response carries webhook.secret once. Store it then: no later response returns it.
Verify the signature
Every delivery is an HTTPPOST signed under the Standard Webhooks scheme. The signature is HMAC-SHA256 over <webhook-id>.<webhook-timestamp>.<raw body>, keyed with the base64-decoded part of webhook.secret after whsec_. Check it on the raw request body, before you parse the JSON.
These handlers listen on port 8080, refuse a body over 1 MB, reject a delivery whose signature doesn’t match or whose timestamp is more than 5 minutes from now, and print the event’s id and type. The size cap and read timeouts stop an unsigned sender from tying up memory or connections before the signature check. The TypeScript and Python handlers use only the standard library. The Go handler uses VerifyWebhook from the SDK:
evt_9f2c4e1a7b3d4c5e8f6a0b1c2d3e4f5a monitor.result.found and answers 204. A forged delivery, or one whose timestamp is more than 5 minutes off, gets 400.
Drop repeated events
These handlers only verify and print. A retry of an event you already handled passes the signature check too, because an event keeps itsid across retries. Record the id and do the event’s work in one transaction: if the work fails, the record rolls back too, so the retry runs it again. Skip an event whose id is already recorded, and still answer 2xx so Keenable stops retrying. In Python with SQLite, when the work writes to the same database:
handle_once(event, work) after the signature check and answer 204. Each call opens its own connection, so concurrent deliveries on the threaded handler never share a transaction. If it raises, answer 500: the transaction rolls back and Keenable delivers the event again. For work outside the database, such as a call to another API, store the event as pending in the same insert, answer 204, and have a worker mark it done after the call succeeds. The Go handler needs Go SDK 0.2.0 or later.
SDK 0.2.0 adds verify_webhook to the Python and Rust SDKs and verifyWebhook to the TypeScript SDK. They do the same checks and return a typed event. See Verify a webhook for a handler in each language. Any Standard Webhooks library also verifies these deliveries with the monitor’s webhook.secret.
Test your handler locally
You don’t need a real event to test your handler. This script signs a samplemonitor.result.found delivery with your secret, the same way Keenable does, and sends it to localhost:8080:
send_test_event.py
KEENABLE_WEBHOOK_SECRET. The script prints 204 and your handler prints evt_test_0001 monitor.result.found. To test without a real secret, set both to a generated one:
Answer fast and drop repeats
Keenable delivers events under these rules. Build your handler around them:Debug failed deliveries
List deliveries shows each event of the last 7 days with its attempts, its last error and when the next attempt is due. This request lists the latest 10:type, attempts, delivered_at, last_error and next_attempt_at. With the CLI, keenable monitors deliveries mon_3kq9z2c8f1a04b7d9e6f5a21 -p prints the same list. Read last_error against this table:
If
data is empty, the monitor hasn’t sent anything. Check that webhook.events is empty or lists monitor.result.found, and that new results exist with Read monitor results.
Related pages
- Webhook payload: the headers, the envelope and the
dataof every event type. - Create a monitor: set the webhook in the create request.
- Monitors: which events a monitor sends by default.