API Reference

Base URL: https://api.hookbase.app

Authentication

All API requests require authentication via Bearer token:

Authorization: Bearer {api_key}

Response Format

Successful responses return JSON in this format:

{
  "data": { ... }
}

List responses include pagination:

{
  "data": [ ... ],
  "total": 100,
  "limit": 50,
  "offset": 0,
  "hasMore": true
}

Error responses:

{
  "error": {
    "message": "Error description",
    "code": "error_code"
  }
}

---

Applications

List Applications

GET /applications

Query Parameters:

Parameter	Type	Description
limit	number	Max results (default: 50, max: 100)
offset	number	Pagination offset
search	string	Search by name

Get Application

GET /applications/{id}

Get Application by UID

GET /applications/uid/{uid}

Create Application

POST /applications

Body:

{
  "name": "Acme Corp",
  "uid": "customer_123",
  "metadata": { "plan": "enterprise" }
}

Update Application

PATCH /applications/{id}

Body:

{
  "name": "New Name",
  "metadata": { "plan": "business" }
}

Delete Application

DELETE /applications/{id}

---

Endpoints

List Endpoints

GET /applications/{appId}/endpoints

Get Endpoint

GET /applications/{appId}/endpoints/{id}

Create Endpoint

POST /applications/{appId}/endpoints

Body:

{
  "url": "https://example.com/webhooks",
  "description": "Production endpoint",
  "headers": { "X-Custom": "value" },
  "filterTypes": ["order.*"],
  "rateLimit": 100,
  "rateLimitPeriod": 60
}

Response includes signing secret:

{
  "data": {
    "id": "ep_123",
    "url": "https://example.com/webhooks",
    "secret": "whsec_..."
  }
}

Update Endpoint

PATCH /applications/{appId}/endpoints/{id}

Delete Endpoint

DELETE /applications/{appId}/endpoints/{id}

Rotate Secret

POST /applications/{appId}/endpoints/{id}/rotate-secret

Get Statistics

GET /applications/{appId}/endpoints/{id}/stats

Recover Circuit

POST /applications/{appId}/endpoints/{id}/recover

---

Event Types

List Event Types

GET /event-types

Query Parameters:

Parameter	Type	Description
category	string	Filter by category
isArchived	boolean	Include archived
search	string	Search by name

Get Event Type

GET /event-types/{id}

Get Event Type by Name

GET /event-types/name/{name}

Create Event Type

POST /event-types

Body:

{
  "name": "order.created",
  "displayName": "Order Created",
  "description": "Triggered when an order is placed",
  "category": "Orders",
  "schema": { "type": "object" }
}

Update Event Type

PATCH /event-types/{id}

Delete Event Type

DELETE /event-types/{id}

---

Subscriptions

List Subscriptions

GET /applications/{appId}/subscriptions

Query Parameters:

Parameter	Type	Description
endpointId	string	Filter by endpoint
eventTypeId	string	Filter by event type
isEnabled	boolean	Filter by status

Get Subscription

GET /applications/{appId}/subscriptions/{id}

Create Subscription

POST /applications/{appId}/subscriptions

Body:

{
  "endpointId": "ep_123",
  "eventTypeId": "evt_456"
}

Update Subscription

PATCH /applications/{appId}/subscriptions/{id}

Body:

{
  "isEnabled": false
}

Delete Subscription

DELETE /applications/{appId}/subscriptions/{id}

---

Messages

Send Message

POST /applications/{appId}/messages

Body:

{
  "eventType": "order.created",
  "payload": {
    "orderId": "ord_123",
    "amount": 99.99
  },
  "eventId": "unique_event_id",
  "metadata": { "source": "api" },
  "endpointIds": ["ep_123"]
}

Response:

{
  "data": {
    "messageId": "msg_123",
    "outboundMessages": [
      { "id": "out_1", "endpointId": "ep_123", "status": "pending" }
    ]
  }
}

List Messages

GET /applications/{appId}/messages

Query Parameters:

Parameter	Type	Description
eventType	string	Filter by event type
startDate	string	ISO date
endDate	string	ISO date

Get Message

GET /applications/{appId}/messages/{id}

Resend Message

POST /applications/{appId}/messages/{id}/resend

List Outbound Messages

GET /applications/{appId}/outbound-messages

Query Parameters:

Parameter	Type	Description
endpointId	string	Filter by endpoint
status	string	pending, success, failed, exhausted
eventType	string	Filter by event type

Get Outbound Message

GET /applications/{appId}/outbound-messages/{id}

List Attempts

GET /applications/{appId}/outbound-messages/{id}/attempts

Retry Outbound Message

POST /applications/{appId}/outbound-messages/{id}/retry

---

Portal Tokens

Create Portal Token

POST /applications/{appId}/portal-tokens

Body:

{
  "expiresIn": 3600
}

Response:

{
  "data": {
    "id": "ptk_123",
    "token": "whpt_...",
    "expiresAt": "2024-01-15T11:30:00Z"
  }
}

Revoke Portal Token

DELETE /applications/{appId}/portal-tokens/{id}

---

Portal API

The Portal API is authenticated with portal tokens (whpt_...) and provides a subset of functionality for embedded use.

Get Application Info

GET /portal/application

Endpoints

GET /portal/endpoints
POST /portal/endpoints
PATCH /portal/endpoints/{id}
DELETE /portal/endpoints/{id}
POST /portal/endpoints/{id}/rotate-secret

Event Types

GET /portal/event-types

Subscriptions

GET /portal/subscriptions
POST /portal/subscriptions
DELETE /portal/subscriptions/{id}

Messages

GET /portal/messages
GET /portal/messages/{id}

---

Webhook Signature Verification

Webhooks include signature headers for verification:

Header	Description
webhook-id	Unique message identifier
webhook-timestamp	Unix timestamp
webhook-signature	v1,{signature}

Verify using:

signature = HMAC-SHA256(
  key: base64_decode(secret),
  message: "{webhook-id}.{webhook-timestamp}.{body}"
)

---

Status Codes

Code	Description
200	Success
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
429	Rate Limited
500	Server Error

---

Rate Limits

Requests are rate limited per API key:

Endpoint	Limit
General API	1000/minute
Message Send	10000/minute
Portal Tokens	100/hour

Headers:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset