Hole Monitor

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:

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.