API Reference

Hookbase provides a RESTful API for managing all aspects of your webhook infrastructure.

Postman Collection

Download the Postman Collection for quick API exploration.

OpenAPI Specification

Download the OpenAPI 3.0 Spec for SDK generation, API testing tools, and automated documentation.

Compatible with tools like Swagger UI, Redocly, and any OpenAPI code generator.

Base URL

https://api.hookbase.app

Authentication

All API requests require authentication. See Authentication for details.

URL Patterns

Hookbase supports two URL patterns for API requests:

API Key Authentication (Recommended)

When using an API key, the organization is inferred automatically from the key — no need to include an organization ID in the URL:

curlJavaScriptPython

bash

curl https://api.hookbase.app/api/sources \
  -H "Authorization: Bearer whr_your_api_key"

javascript

const response = await fetch('https://api.hookbase.app/api/sources', {
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const data = await response.json();

python

import requests

response = requests.get(
    'https://api.hookbase.app/api/sources',
    headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()

JWT Authentication

When using JWT tokens (e.g. from the dashboard), you must include the organization ID in the path:

curlJavaScriptPython

bash

curl https://api.hookbase.app/api/organizations/{orgId}/sources \
  -H "Authorization: Bearer your_jwt_token"

javascript

const response = await fetch('https://api.hookbase.app/api/organizations/{orgId}/sources', {
  headers: {
    'Authorization': 'Bearer your_jwt_token'
  }
});
const data = await response.json();

python

import requests

response = requests.get(
    'https://api.hookbase.app/api/organizations/{orgId}/sources',
    headers={'Authorization': 'Bearer your_jwt_token'}
)
data = response.json()

TIP

All examples in this documentation use the simplified API key pattern. If you're using JWT authentication, prefix the resource path with /api/organizations/{orgId}.

Request Format

All requests should use Content-Type: application/json
Request bodies should be JSON-encoded
URL parameters should be URL-encoded

Response Format

All responses are JSON-encoded with the following structure:

Success Response

json

{
  "id": "src_abc123",
  "name": "My Source",
  "createdAt": "2024-01-15T10:30:00Z"
}

Or for lists:

json

{
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}

Error Response

json

{
  "error": "Not found",
  "message": "Source with ID src_xyz not found",
  "code": "RESOURCE_NOT_FOUND"
}

HTTP Status Codes

Code	Description
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request (invalid input)
401	Unauthorized (missing or invalid auth)
403	Forbidden (insufficient permissions)
404	Not Found
409	Conflict (duplicate resource)
422	Unprocessable Entity (validation error)
429	Too Many Requests (rate limited)
500	Internal Server Error

Rate Limits

Rate limits vary by plan:

Plan	Requests/minute
Free	60
Starter	300
Pro	1,000
Business	3,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705312800

Pagination

List endpoints support pagination:

bash

GET /api/sources?page=1&pageSize=20

Parameter	Default	Max
page	1	-
pageSize	20	100

Filtering

Many list endpoints support filtering:

bash

GET /api/events?status=delivered&sourceId=src_abc

Sorting

Sort results using the sort parameter:

bash

GET /api/events?sort=-createdAt

Prefix with - for descending order.

API Endpoints

Core Resources

Resource	Description
Sources	Webhook receive endpoints
Destinations	Delivery targets
Routes	Source to destination mappings
Events	Received webhook events
Deliveries	Delivery attempts and status

Webhook Ingest

Endpoint	Description
Webhook Ingest	Public endpoint for receiving webhooks

Authentication & Access

Resource	Description
Authentication	JWT tokens and session management
API Keys	Programmatic access tokens

Development Tools

Resource	Description
Tunnels	Local development tunnels

Advanced Features

Resource	Description
Transforms	Payload transformation functions
Filters	Conditional routing rules
Schemas	Payload validation schemas
Cron Jobs	Scheduled webhook triggers

SDKs

Official SDKs are available for:

JavaScript/TypeScript: npm install @webhookrelay/sdk
Python: pip install webhookrelay
Go: go get github.com/webhookrelay/go-sdk

Quick Examples

Create a Source

curlJavaScriptPython

bash

curl -X POST https://api.hookbase.app/api/sources \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "GitHub", "slug": "github"}'

javascript

const response = await fetch('https://api.hookbase.app/api/sources', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer whr_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'GitHub',
    slug: 'github'
  })
});
const data = await response.json();

python

import requests

response = requests.post(
    'https://api.hookbase.app/api/sources',
    headers={
        'Authorization': 'Bearer whr_your_api_key',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'GitHub',
        'slug': 'github'
    }
)
data = response.json()

List Events

curlJavaScriptPython

bash

curl https://api.hookbase.app/api/events \
  -H "Authorization: Bearer whr_your_api_key"

javascript

const response = await fetch('https://api.hookbase.app/api/events', {
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const data = await response.json();

python

import requests

response = requests.get(
    'https://api.hookbase.app/api/events',
    headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()

Replay an Event

curlJavaScriptPython

bash

curl -X POST https://api.hookbase.app/api/events/{eventId}/replay \
  -H "Authorization: Bearer whr_your_api_key"

javascript

const response = await fetch('https://api.hookbase.app/api/events/{eventId}/replay', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const data = await response.json();

python

import requests

response = requests.post(
    'https://api.hookbase.app/api/events/{eventId}/replay',
    headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()

API Reference ​

Postman Collection ​

OpenAPI Specification ​

Base URL ​

Authentication ​

URL Patterns ​

API Key Authentication (Recommended) ​

JWT Authentication ​

Request Format ​

Response Format ​

Success Response ​

Error Response ​

HTTP Status Codes ​

Rate Limits ​

Pagination ​

Filtering ​

Sorting ​

API Endpoints ​

Core Resources ​

Webhook Ingest ​

Authentication & Access ​

Development Tools ​

Advanced Features ​

SDKs ​

Quick Examples ​

Create a Source ​

List Events ​

Replay an Event ​

API Reference

Postman Collection

OpenAPI Specification

Base URL

Authentication

URL Patterns

API Key Authentication (Recommended)

JWT Authentication

Request Format

Response Format

Success Response

Error Response

HTTP Status Codes

Rate Limits

Pagination

Filtering

Sorting

API Endpoints

Core Resources

Webhook Ingest

Authentication & Access

Development Tools

Advanced Features

SDKs

Quick Examples

Create a Source

List Events

Replay an Event