RelayHQ Documentation

RelayHQ is a reliable webhook infrastructure layer. It gives you permanent inbound webhook URLs, queues every request durably, fans them out to any number of destination services, and retries failures automatically — all with full observability through the dashboard.

This page covers the quick-start guide, core concepts, a full REST API reference, and dashboard usage tips.

Quick Start

Get from zero to receiving webhooks in under 5 minutes.

1. Create an account

Sign up at dashboard.relayhq.org with your email, Google, or GitHub account. A workspace is created for you automatically.

2. Create your first endpoint

In the dashboard, click New endpoint and give it a name (e.g. "Stripe Payments"). You'll immediately get a permanent relay URL:

https://hooks.relayhq.org/in/<your-endpoint-token>

3. Add a destination

Destinations are the services RelayHQ will forward webhooks to. Add one from the endpoint modal or the endpoint detail page. Example:

https://api.myapp.com/webhooks/stripe

You can optionally add custom HTTP headers (e.g. Authorization: Bearer ...).

4. Point your provider at the relay URL

Go to Stripe (or GitHub, Shopify, etc.) and set the webhook endpoint to your relay URL. RelayHQ will confirm receipt with a 200 OK in under 50ms.

5. Verify delivery

Open the endpoint in the dashboard → Request logs. Every inbound request appears there with full headers, body, and source IP. Click any request to expand it and see per-destination delivery attempts.

Authentication

The RelayHQ dashboard uses session-based authentication (cookies). For programmatic API access, use an API key.

Creating an API key

Go to Settings → API Keys → Create key. Copy the key immediately — it is shown only once.

Using an API key

Pass the key as a Bearer token in the Authorization header on every request:

Authorization: Bearer rhk_live_xxxxxxxxxxxx

Endpoints

An endpoint is a named, permanent inbound webhook URL. Each endpoint gets a unique token (e.g. abc123) used in the relay URL hooks.relayhq.org/in/<token>.

Endpoints can be paused (stops delivery to destinations without losing requests) or deleted. Deleting an endpoint also removes all associated destinations, requests, and delivery history.

Destinations

A destination is a URL that RelayHQ forwards incoming webhooks to. Each endpoint can have unlimited destinations. When a webhook arrives, RelayHQ fans it out to all active destinations simultaneously.

Destinations support custom request headers (e.g. for authorization) and can be individually enabled/disabled without deleting them.

Routing Rules

Routing rules let you conditionally forward webhooks to a destination based on the request payload or headers. A destination with routing rules only receives webhooks that match the rules.

Each rule has a field (JSON path like $.type or header name like x-event-type), an operator (eq, neq, contains, startsWith, exists), and a value. Multiple rules on a destination are combined with AND/OR logic.

Field:    $.type
Operator: startsWith
Value:    payment_intent
Logic:    AND

Request Logs

Every inbound webhook is stored as a request with:

• Full HTTP headers
• Raw request body (any content type)
• Source IP address
• HTTP method
• Received timestamp

Requests are retained according to your plan (7 days on Free, up to 1 year on Team). You can filter, search, and replay any request.

Delivery Attempts

For each destination, RelayHQ records every delivery attempt with: HTTP status code, response time (ms), attempt number, and timestamp. You can view the last 15 attempts per destination directly in the dashboard.

Retries & Exponential Backoff

If a destination responds with a non-2xx status (or times out), RelayHQ automatically retries with exponential backoff:

Attempt 1:  immediately
Attempt 2:  30 seconds later
Attempt 3:  5 minutes later
Attempt 4:  30 minutes later
Attempt 5:  2 hours later
After 5 failures: marked as failed, alert sent

API Reference

The RelayHQ REST API is available at:

Base URL: https://api.relayhq.org

All requests must include an Authorization: Bearer <api-key> header or a valid session cookie. All request bodies are JSON (Content-Type: application/json). All responses are JSON.

Workspaces

{
  "id": "ws_abc123",
  "name": "My Workspace",
  "slug": "my-workspace",
  "plan": "starter",
  "requestCount": 4821,
  "createdAt": "2026-01-15T09:00:00Z"
}

{
  "name": "Acme Corp"
}

{
  "id": "ws_abc123",
  "name": "Acme Corp",
  "slug": "acme-corp"
}

Endpoints

[
  {
    "id": "ep_xxx",
    "name": "Stripe Payments",
    "token": "abc123",
    "paused": false,
    "createdAt": "2026-01-20T10:00:00Z"
  }
]

{
  "name": "Stripe Payments",
  "destinations": [
    {
      "url": "https://api.myapp.com/webhooks/stripe",
      "headers": { "Authorization": "Bearer sk_live_xxx" }
    }
  ]
}

{
  "id": "ep_xxx",
  "name": "Stripe Payments",
  "token": "abc123",
  "paused": false,
  "relayUrl": "https://hooks.relayhq.org/in/abc123"
}

{
  "name": "Stripe (Production)",
  "paused": true
}

Destinations

[
  {
    "id": "dst_xxx",
    "url": "https://api.myapp.com/webhooks/stripe",
    "enabled": true,
    "headers": { "Authorization": "Bearer sk_live_xxx" },
    "createdAt": "2026-01-20T10:00:00Z"
  }
]

{
  "url": "https://api.myapp.com/webhooks/stripe",
  "headers": {
    "Authorization": "Bearer sk_live_xxx",
    "X-Custom-Header": "value"
  }
}

{
  "id": "dst_xxx",
  "url": "https://api.myapp.com/webhooks/stripe",
  "enabled": true
}

{
  "url": "https://api.myapp.com/webhooks/stripe-v2",
  "enabled": false,
  "headers": {}
}

[
  {
    "id": "att_xxx",
    "status": "delivered",
    "httpStatus": 200,
    "durationMs": 142,
    "attempt": 1,
    "createdAt": "2026-05-28T11:30:00Z"
  },
  {
    "id": "att_yyy",
    "status": "failed",
    "httpStatus": 503,
    "durationMs": 30000,
    "attempt": 2,
    "createdAt": "2026-05-28T11:00:30Z"
  }
]

Routing Rules

[
  {
    "id": "rr_xxx",
    "field": "$.type",
    "operator": "startsWith",
    "value": "payment_intent",
    "logic": "AND",
    "enabled": true
  }
]

{
  "field": "$.type",
  "operator": "eq",
  "value": "payment_intent.succeeded",
  "logic": "AND"
}

{
  "enabled": false
}

Requests

[
  {
    "id": "req_xxx",
    "method": "POST",
    "sourceIp": "54.187.174.169",
    "headers": { "content-type": "application/json", "stripe-signature": "..." },
    "receivedAt": "2026-05-28T11:30:00Z"
  }
]

{
  "id": "req_xxx",
  "method": "POST",
  "sourceIp": "54.187.174.169",
  "headers": { "content-type": "application/json" },
  "body": "{ "type": "payment_intent.succeeded", "data": { "amount": 4999 } }",
  "receivedAt": "2026-05-28T11:30:00Z"
}

{ "queued": true }

API Keys

[
  {
    "id": "key_xxx",
    "name": "CI/CD Pipeline",
    "prefix": "rhk_live_xxxx",
    "createdAt": "2026-04-01T00:00:00Z",
    "lastUsedAt": "2026-05-28T10:00:00Z"
  }
]

{
  "name": "CI/CD Pipeline"
}

{
  "id": "key_xxx",
  "name": "CI/CD Pipeline",
  "key": "rhk_live_xxxxxxxxxxxxxxxxxxxx"
}

Creating an Endpoint

1. Open the dashboard → Endpoints page.
2. Click New endpoint.
3. Enter a name and optionally add one or more destination URLs.
4. Click Create endpoint.
5. Copy your relay URL (e.g. hooks.relayhq.org/in/abc123).

Adding Destinations

From the endpoint card on the Endpoints page, click Add destination. Or open the endpoint detail page and go to the Destinations tab.

Each destination has its own delivery log, routing rules, and enable/disable toggle accessible directly from the endpoint detail view.

Viewing Logs

Click any endpoint name to open its detail page. The Request logs tab shows every inbound request. Click a row to expand the full headers and body. Switch to the Destinations tab to see per-destination delivery history.

Replaying Requests

In the request detail panel, click the Replay button. RelayHQ re-enqueues the original request and delivers it to all currently active destinations. The new delivery attempts appear in the destination logs within seconds.