HookCatcher API Reference

The HookCatcher API allows you to programmatically manage webhook endpoints and retrieve captured requests. Use it to integrate HookCatcher into your development workflows, CI/CD pipelines, or custom tooling.

REST API

JSON

Team Plan Required

Base URL: https://hookcatcher.dev/api/v1

Quick Start

Get up and running with the HookCatcher API in under 5 minutes.

Generate an API Key

Navigate to Settings → API Keys and create a new API key. Your key will start with hk_.

Make Your First Request

Try listing your endpoints with a simple GET request:

curl -X GET "https://hookcatcher.dev/api/v1/endpoints" \
  -H "Authorization: Bearer hk_your_api_key"

Understand the Response

You'll receive a JSON response with your endpoints and pagination info:

{
  "endpoints": [
    {
      "id": "abc123",
      "code": "xyz789",
      "name": "My Webhook",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "count": 1
  }
}

View full endpoint documentation

Authentication

The HookCatcher API uses Bearer token authentication. Include your API key in the Authorization header of every request.

API Key Format

API keys always start with the hk_ prefix. You can generate keys in your account settings.

Authorization: Bearer hk_your_api_key

Keep Your API Keys Secret

Never expose your API keys in client-side code, public repositories, or logs. If a key is compromised, revoke it immediately in your settings.

Authentication Errors

401

Invalid or missing API key

403

Your plan does not have API access (Team plan required)

Endpoints

Manage your webhook endpoints programmatically.

GET

/endpoints

List endpoints

Retrieve a paginated list of all webhook endpoints belonging to the authenticated user.

Query Parameters

Name	Type	Description
`limit`	`integer`	Maximum number of endpoints to return (1-100) Default: `50`
`page`	`integer`	Page number for pagination Default: `1`

Response Fields

endpoints

arrayArray of endpoint objects

pagination.page

integerCurrent page number

pagination.limit

integerItems per page

pagination.count

integerTotal number of endpoints

Example Request

curl -X GET "https://hookcatcher.dev/api/v1/endpoints?limit=10&page=1" \
  -H "Authorization: Bearer hk_your_api_key"

Example Response

{
  "endpoints": [
    {
      "id": "abc123xyz",
      "userId": "user_456",
      "code": "w3bh00k123",
      "name": "Stripe Webhooks",
      "description": "Captures Stripe payment events",
      "responseStatus": 200,
      "responseBody": "{\"success\": true}",
      "responseHeaders": null,
      "responseDelayMs": 0,
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "count": 1
  }
}

Errors

401

Invalid or missing API key

403

Plan does not have API access

429

Rate limit exceeded

POST

/endpoints

Create endpoint

Create a new webhook endpoint. The endpoint will be assigned a unique code that can be used to receive webhooks.

Request Body

Name	Type	Description
`name`	`string`	Friendly name for the endpoint (max 100 chars). Auto-generated if not provided.
`description`	`string`	Optional description (max 1000 chars)

Response Fields

endpoint.id

stringUnique endpoint identifier

endpoint.code

stringURL slug for webhook capture (use in /catch/{code})

endpoint.name

stringEndpoint name

endpoint.isActive

booleanWhether the endpoint is active

Example Request

curl -X POST "https://hookcatcher.dev/api/v1/endpoints" \
  -H "Authorization: Bearer hk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "GitHub Webhooks", "description": "Captures push events"}'

Example Response

{
  "endpoint": {
    "id": "new_endpoint_id",
    "userId": "user_456",
    "code": "gh_w3bh00k789",
    "name": "GitHub Webhooks",
    "description": "Captures push events",
    "responseStatus": 200,
    "responseBody": "{\"success\": true}",
    "responseHeaders": null,
    "responseDelayMs": 0,
    "isActive": true,
    "createdAt": "2024-01-15T12:00:00.000Z"
  }
}

Errors

400

Invalid JSON or field types

401

Invalid or missing API key

403

Plan does not have API access or endpoint limit reached

GET

/endpoints/{id}

Get endpoint with requests

Retrieve a specific endpoint along with its captured webhook requests.

Path Parameters

Name	Type	Description
`id` required	`string`	The endpoint ID

Query Parameters

Name	Type	Description
`limit`	`integer`	Maximum number of requests to return (1-100) Default: `50`

Response Fields

endpoint

objectThe endpoint object

requests

arrayArray of captured request objects

requests[].method

stringHTTP method (GET, POST, etc.)

requests[].headers

stringRequest headers as JSON string

requests[].bodynullable

stringRequest body

requests[].receivedAt

datetimeWhen the request was received

Example Request

curl -X GET "https://hookcatcher.dev/api/v1/endpoints/abc123?limit=10" \
  -H "Authorization: Bearer hk_your_api_key"

Example Response

{
  "endpoint": {
    "id": "abc123",
    "code": "w3bh00k123",
    "name": "Stripe Webhooks",
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  "requests": [
    {
      "id": "req_001",
      "endpointId": "abc123",
      "method": "POST",
      "headers": "{\"content-type\": \"application/json\"}",
      "body": "{\"type\": \"payment_intent.succeeded\"}",
      "bodyType": "json",
      "contentType": "application/json",
      "ipAddress": "54.187.174.169",
      "receivedAt": "2024-01-15T11:00:00.000Z"
    }
  ]
}

Errors

401

Invalid or missing API key

403

Plan does not have API access

404

Endpoint not found or no access

GET

/endpoints/{id}/requests

List endpoint requests

Retrieve a paginated list of captured webhook requests for a specific endpoint. Uses cursor-based pagination for efficient traversal of large datasets.

Path Parameters

Name	Type	Description
`id` required	`string`	The endpoint ID

Query Parameters

Name	Type	Description
`limit`	`integer`	Maximum number of requests to return (1-100) Default: `50`
`cursor`	`string`	Cursor for pagination (use nextCursor from previous response)

Response Fields

requests

arrayArray of captured request objects

pagination.limit

integerItems per page

pagination.hasMore

booleanWhether more results exist

pagination.nextCursornullable

stringCursor for next page (null if no more results)

Example Request

curl -X GET "https://hookcatcher.dev/api/v1/endpoints/abc123/requests?limit=10" \
  -H "Authorization: Bearer hk_your_api_key"

Example Response

{
  "requests": [
    {
      "id": "req_001",
      "endpointId": "abc123",
      "method": "POST",
      "headers": "{\"content-type\": \"application/json\"}",
      "body": "{\"type\": \"payment_intent.succeeded\"}",
      "bodyType": "json",
      "contentType": "application/json",
      "ipAddress": "54.187.174.169",
      "receivedAt": "2024-01-15T11:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "hasMore": true,
    "nextCursor": "req_001"
  }
}

Errors

401

Invalid or missing API key

403

Plan does not have API access

404

Endpoint not found or no access

DELETE

/endpoints/{id}

Delete endpoint

Permanently delete an endpoint and all its captured requests. This action cannot be undone.

Path Parameters

Name	Type	Description
`id` required	`string`	The endpoint ID to delete

Response Fields

success

booleanAlways true on successful deletion

Example Request

curl -X DELETE "https://hookcatcher.dev/api/v1/endpoints/abc123" \
  -H "Authorization: Bearer hk_your_api_key"

Example Response

{
  "success": true
}

Errors

401

Invalid or missing API key

403

Plan does not have API access

404

Endpoint not found

Webhook URLs

Each endpoint has a unique code that forms its webhook URL. Configure third-party services to send webhooks to this URL to capture them in HookCatcher.

URL Format:

https://hookcatcher.dev/catch/{code}

The code is a unique 16-character identifier returned when you create an endpoint or list your endpoints via the API.

When a webhook is sent to this URL, HookCatcher captures the request (method, headers, body, etc.) and makes it available via the Get Endpoint API.

Errors

The API returns standard HTTP status codes along with JSON error messages. All errors follow this format:

{
  "error": "Error message describing what went wrong"
}

Status	Description	Resolution
400	Bad Request	Check your request body is valid JSON with correct field types
401	Unauthorized	Verify your API key is correct and starts with `hk_`
403	Forbidden	API access requires Team plan. Upgrade at /pricing
404	Not Found	The resource doesn't exist or you don't have access
429	Rate Limited	Wait and retry. Check `Retry-After` header
500	Server Error	Retry the request. Contact support if it persists
503	Service Unavailable	Temporary outage. Retry with exponential backoff

Rate Limiting

API requests are rate limited to ensure fair usage and platform stability.

Current Limit

60 requests / minute

Per API key

Rate Limit Headers

When you hit the rate limit, the response includes these headers:

Retry-AfterSeconds until you can retry

X-RateLimit-ResetTimestamp (ms) when the limit resets

Example 429 Response

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Reset: 1705320000000
Content-Type: application/json

{
  "error": "Rate limit exceeded"
}

Best Practices

Implement exponential backoff when retrying failed requests
Cache responses when possible to reduce API calls
Use pagination with reasonable limits to avoid fetching too much data at once
Check the Retry-After header before retrying rate-limited requests

Need help? Contact support