Quick start
The API is at https://api.holemonitor.live. Send your key as Authorization: Bearer hm_.... Create keys in the dashboard.
1. Create an endpoint
curl -s https://api.holemonitor.live/v1/endpoints \
-H "Authorization: Bearer $HOLE_MONITOR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"url":"https://hooks.example.com/hole-monitor","description":"prod receiver"}'
The response includes secret, a whsec_ value. It is shown once. Store it where your receiver reads its secrets.
2. Verify the endpoint
A new endpoint is unverified and receives nothing but one verification request. That request is signed like any delivery and its body holds a code. The endpoint becomes active when either:
- your receiver answers the verification request with a 2xx response whose body contains the code, or
- you send the code yourself:
curl -s https://api.holemonitor.live/v1/endpoints/$ENDPOINT_ID/verify \
-H "Authorization: Bearer $HOLE_MONITOR_API_KEY" \
-H "Content-Type: application/json" -d '{"code":"..."}'
POST /v1/endpoints/{id}/verify with an empty body sends the verification request again, at most 5 times an hour.
3. Add a filter
curl -s https://api.holemonitor.live/v1/endpoints/$ENDPOINT_ID/filters \
-H "Authorization: Bearer $HOLE_MONITOR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"conditions":{"packages":[{"ecosystem":"npm","name":"next"},{"purl":"pkg:pypi/django"}],"min_cvss":7}}'
To keep filters in a repository, PUT /v1/endpoints/{id}/filters replaces the whole set from one JSON document. See Filters.
4. Send a test event
curl -s -X POST https://api.holemonitor.live/v1/endpoints/$ENDPOINT_ID/test \
-H "Authorization: Bearer $HOLE_MONITOR_API_KEY" -H "Content-Type: application/json" -d '{"type":"published"}'
The test body has database_specific.event.test set to true.
5. Receive
Verify the signature, reject old timestamps, discard repeated webhook-id values and return 2xx quickly. See Webhooks for code, or deploy a receiver template.