Authenticate | HooksDash

Welcome to the HooksDash API documentation. This API provides programmatic access to webhook endpoint management, request inspection, and replay functionality.

API Overview

The HooksDash API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

HooksDash supports two authentication methods:

JWT Bearer Token - For web application access
API Key - For CLI and programmatic access

See Authentication for detailed information.

API Sections

Authentication - CLI session management and API key validation
Endpoints - Create and manage webhook endpoints
Requests - Inspect and replay webhook requests
Webhooks - Receive webhooks (public endpoint)

Rate Limits

Rate limits are applied per-endpoint based on your tier:

Tier	Requests per Minute
Free	10
Starter	60
Pro	300
Enterprise	1000

When rate limit is exceeded, the API returns a 429 Too Many Requests response.

Error Codes

HooksDash uses conventional HTTP response codes to indicate the success or failure of an API request.

Status Code	Meaning
200	OK - Request successful
201	Created - Resource created successfully
400	Bad Request - Invalid request format or validation error
401	Unauthorized - Missing or invalid authentication
403	Forbidden - Authenticated but not authorized (e.g., tier limit)
404	Not Found - Resource doesn't exist
409	Conflict - Resource already exists (e.g., duplicate slug)
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end

Error Response Format

All error responses follow this format:


{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

For validation errors, additional details are included:


{
  "statusCode": 400,
  "message": [
    "name must be longer than or equal to 1 characters",
    "slug must match the required pattern"
  ],
  "error": "Bad Request"
}

Pagination

List endpoints support pagination using page and limit query parameters:

GET /api/endpoints?page=1&limit=20

Paginated responses include metadata:


{
  "data": [...],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

Default values:

page: 1
limit: 20
Maximum limit: 100

Tier Limits

Different tiers have different resource limits:

Resource	Free	Starter	Pro	Enterprise
Max Endpoints	3	20	50	Unlimited
Max Requests/Endpoint	100	1,000	5,000	Unlimited
Request Retention	24h	7 days	7 days	30 days
Max Tunnels	1	3	10	Unlimited

Webhooks

The public webhook receiver is available at:

POST https://hooksdash.ibadsiddiqui.dev/api/h/{slug}

This endpoint accepts all HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.) and captures:

Request method
Headers
Query parameters
Request body
IP address
Timestamp

See Webhooks for detailed information.

SDK and Tools

Official CLI


npm install -g hooksdash

# Authenticate
hooksdash login

# Forward webhooks to localhost
hooksdash forward --port 3000 --endpoint my-endpoint

cURL Examples

Create an endpoint:


curl -X POST https://hooksdash-api.ibadsiddiqui.dev/api/endpoints \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Webhook",
    "description": "Receives Stripe events"
  }'

Send a test webhook:


curl -X POST https://hooksdash.ibadsiddiqui.dev/api/h/my-webhook \
  -H "Content-Type: application/json" \
  -d '{"event": "test"}'

Support

For API support, please:

Visit our documentation at docs.hooksdash.ibadsiddiqui.dev
Report issues on GitHub
Contact support at support@hooksdash.ibadsiddiqui.dev

Changelog

See CHANGELOG.md for API version history and breaking changes.

API Reference