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'