RelayHQ - Documentation

Authentication

All management API endpoints require authentication using an API key.

Authorization: Bearer YOUR_API_KEY

API keys can be configured via environment variables or through the management interface.

Base URL

The API base URL depends on your deployment:

Staging: https://api-staging.relayhq.dev
Production: https://api.relayhq.dev
Local: http://localhost:3000

Webhook Ingestion

POST /api/in/{project_id}

Receive and store webhook events.

Request

POST /api/in/my-project
Content-Type: application/json
X-Idempotency-Key: optional-unique-key

{
  "event": "data",
  "timestamp": "2024-01-01T00:00:00Z"
}

Response

{
  "event_id": "evt_abc123"
}

Features

Accepts any content type (JSON, XML, raw, etc.)
Preserves all request headers
Optional idempotency key for duplicate prevention
Returns 202 Accepted immediately

Event Management

GET /api/events

List events for a project.

GET /api/events?project_id=my-project&status=delivered&limit=100&offset=0
Authorization: Bearer YOUR_API_KEY

Query Parameters

project_id (required) - Project identifier
status (optional) - Filter by status: pending, delivered, failed
limit (optional, default: 100) - Number of results
offset (optional, default: 0) - Pagination offset

GET /api/events/{event_id}

Get event details including delivery attempts.

GET /api/events/evt_abc123
Authorization: Bearer YOUR_API_KEY

GET /api/events/{event_id}/payload

Retrieve the original webhook payload.

GET /api/events/evt_abc123/payload
Authorization: Bearer YOUR_API_KEY

POST /api/events/{event_id}/replay

Replay an event (re-deliver to configured or custom endpoint).

POST /api/events/evt_abc123/replay
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "target_url": "https://custom-endpoint.com/webhook",
  "headers": {
    "X-Custom-Header": "value"
  }
}

Forwarding Rules

POST /api/projects/{project_id}/forwarding

Create a forwarding rule for a project.

POST /api/projects/my-project/forwarding
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "target_url": "https://customer.com/webhook",
  "method": "POST",
  "headers": {
    "X-Custom-Header": "value"
  },
  "retry_policy": {
    "max_attempts": 5,
    "backoff": "exponential",
    "initial_delay_ms": 1000,
    "max_delay_ms": 600000
  }
}

Retry Policy

max_attempts - Maximum retry attempts (default: 5)
backoff - Strategy: exponential, linear, or fixed
initial_delay_ms - Initial delay in milliseconds (default: 1000)
max_delay_ms - Maximum delay in milliseconds (default: 600000)

GET /api/projects/{project_id}/forwarding

List all forwarding rules for a project.

GET /api/projects/my-project/forwarding
Authorization: Bearer YOUR_API_KEY

PATCH /api/forwarding/{rule_id}

Update a forwarding rule.

PATCH /api/forwarding/rule_xyz
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "active": false,
  "retry_policy": {
    "max_attempts": 10
  }
}

Response Codes

200 - Success
201 - Created
202 - Accepted (webhook ingestion)
400 - Bad Request
401 - Unauthorized (missing/invalid API key)
404 - Not Found
500 - Internal Server Error

Error Response Format

{
  "error": "Error message description"
}

Examples

cURL Example

# Ingest a webhook
curl -X POST https://api-staging.relayhq.dev/api/in/my-project \
  -H "Content-Type: application/json" \
  -d '{"event": "user.created", "user_id": "123"}'

# List events
curl -X GET "https://api-staging.relayhq.dev/api/events?project_id=my-project" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create forwarding rule
curl -X POST https://api-staging.relayhq.dev/api/projects/my-project/forwarding \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://myapp.com/webhook",
    "retry_policy": {
      "max_attempts": 5,
      "backoff": "exponential"
    }
  }'

API Documentation