Skip to content

Docs / Reference

WebhookHQ REST API (v1)

Manage endpoints and read events from your own code: CI pipelines, scripts, dashboards. Reading endpoints and events works on every plan (it's what the CLI uses); creating, renaming and deleting endpoints is on the Pro plan and above.

Authentication

Create an access token on the Access tokens tab and send it as a bearer token:

curl https://app.webhookhq.dev/api/v1/endpoints -H "Authorization: Bearer whq_..."
  • Personal tokens act as you: they see the workspaces you can open and change endpoints only where you're an editor or manager. They stop working if you leave the organization.
  • Service tokens (owners and admins) see the whole organization.

Each token can make 600 requests a minute, on every plan; past that you get 429.

Errors

Errors are JSON with a machine-readable error, a human message and the request_id (also in every response's X-Request-Id header; quote it to support and we can find the request):

{ "error": "plan_required", "message": "Creating, changing and deleting through the API is on the Pro plan and above. Reading works on every plan.", "request_id": "3f2a9c1e-5b7d-4e8a-9f60-2c4d8e1b7a35" }
Status error When
400 invalid_time, invalid_jsonpath A malformed before/since time or q expression
401 invalid_token Missing, expired or revoked token
403 plan_required, forbidden Creating, renaming or deleting on a plan without the API (Free, Developer), or no edit access to the workspace
404 not_found No such record, or the token can't see it
422 invalid Validation failed; errors lists them by field
429 rate_limited Over 600 requests a minute
503 archive_unavailable An event older than 30 days (its body is archived) couldn't be loaded just now; try again

Endpoints

Request Does
GET /api/v1/endpoints[?workspace=<slug>] Lists endpoints
GET /api/v1/endpoints/:slug One endpoint
POST /api/v1/endpoints Creates one: workspace (slug, required), name (required), slug (optional; random when left out)
PATCH /api/v1/endpoints/:slug Renames it: name; slug too until webhooks have arrived
DELETE /api/v1/endpoints/:slug Deletes it and its events
{ "endpoint": { "id": "07b7…", "name": "CI run", "slug": "ci-run-4821", "url": "https://in.webhookhq.dev/acme/ci-run-4821",
                "workspace": "production", "protected": false, "created_at": "2026-10-27T05:17:48Z" } }

Events

GET /api/v1/events?endpoint=<slug> lists an endpoint's events, newest first, without bodies:

Parameter
type, source Exact event type (invoice.paid) or sender (Stripe)
status Delivery state: delivered, failed or pending
range 1h, 24h, 7d or 30d
since, before ISO 8601 times; page back by passing the previous response's next_before as before
q Search: ids, types and paths partly, body text exactly. Starting with $ it's JSONPath over JSON bodies ($.data.object.customer == "cus_123"), limited to the last 24 hours unless range is set
limit 1–100, default 50
{ "events": [ { "id": "b8df…", "endpoint_id": "4ed3…", "received_at": "2026-10-27T04:56:45.997106Z", "method": "POST",
                "path": "/webhooks", "query": null, "content_type": "application/json", "size": 82,
                "event_type": "charge.refunded", "source": "Stripe" } ],
  "has_more": true, "next_before": "2026-10-27T04:56:45.997106Z" }

GET /api/v1/events/:id returns one event in full: the fields above plus headers, body (text, or base64 when body_encoding is base64), source_ip and its deliveries (state, attempts, last status). A delivery's state is pending, succeeded, failed, cancelled (its destination was removed), held (its event arrived past the plan's monthly events) or dismissed (held, then dismissed by an owner).

Events that arrived past the plan's monthly events (and free margin) are hidden: they're in no list and GET /api/v1/events/:id answers 404 for them, until an upgrade shows that month's again.

Example: check a CI run received what it should

curl -s "https://app.webhookhq.dev/api/v1/events?endpoint=ci-run-4821&type=push" \
  -H "Authorization: Bearer $WHQ_TOKEN" | jq '.events | length'