API Keys & Authentication#

HookRelay uses API keys to authenticate requests to the HookRelay API. This guide explains how to create, manage, and use API keys.

What are API Keys?#

API keys are secret tokens that authenticate your application when making requests to the HookRelay API. They’re used for:

Programmatic access to the HookRelay API
Managing endpoints, events, and other resources
Integrating HookRelay into your CI/CD pipelines
Building custom tooling and automation

Creating API Keys#

In the Dashboard#

Navigate to Settings in the HookRelay dashboard
Go to the API Keys section
Click “Create Key”
Enter a descriptive name (e.g., “Production API”, “CI/CD”, “Local Development”)
Click “Create”
Copy the key immediately - you won’t be able to see it again!

API Key Format#

API keys follow this format:

hr_live_abc123def456...

The prefix hr_live_ indicates this is a live (production) API key.

Using API Keys#

In HTTP Requests#

Include the API key in the Authorization header:

curl https://api.hookrelay.io/v1/endpoints \
  -H "Authorization: Bearer hr_live_abc123..."

In Code#

JavaScript/TypeScript#

const response = await fetch('https://api.hookrelay.io/v1/endpoints', {
  headers: {
    Authorization: `Bearer ${process.env.HOOKRELAY_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

const endpoints = await response.json();

Python#

import requests

headers = {
    'Authorization': f'Bearer {os.environ["HOOKRELAY_API_KEY"]}',
    'Content-Type': 'application/json',
}

response = requests.get(
    'https://api.hookrelay.io/v1/endpoints',
    headers=headers
)

endpoints = response.json()

Node.js#

const https = require('https');

const options = {
  hostname: 'api.hookrelay.io',
  path: '/v1/endpoints',
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.HOOKRELAY_API_KEY}`,
    'Content-Type': 'application/json',
  },
};

const req = https.request(options, (res) => {
  // Handle response
});

req.end();

Managing API Keys#

Viewing API Keys#

In the Settings page, you can see:

Name - The descriptive name you gave the key
Key Prefix - First few characters (for identification)
Created - When the key was created
Last Used - When the key was last used (if ever)

Revoking API Keys#

To revoke (delete) an API key:

Go to Settings → API Keys
Find the key you want to revoke
Click “Revoke”
Confirm the revocation

⚠️ Warning: Revoking an API key immediately invalidates it. Any applications using that key will stop working.

Best Practices for Key Management#

Use Descriptive Names - Name keys by environment or purpose:
- “Production API”
- “Staging API”
- “CI/CD Pipeline”
- “Local Development”
Rotate Regularly - Create new keys periodically and revoke old ones
Never Commit Keys - Never commit API keys to version control
- Use environment variables
- Use secret management services (Vercel, AWS Secrets Manager, etc.)
Limit Key Scope - Use different keys for different purposes when possible
Monitor Usage - Check “Last Used” to identify unused keys that can be revoked

Security Best Practices#

Storing API Keys#

✅ DO:

Store in environment variables
Use secret management services
Use different keys for different environments
Rotate keys regularly

❌ DON’T:

Commit keys to version control
Share keys in chat or email
Use the same key in multiple places
Leave keys in client-side code

Environment Variables#

Local Development#

Create a .env.local file (and add it to .gitignore):

HOOKRELAY_API_KEY=hr_live_abc123...

Vercel#

Go to your project settings
Navigate to Environment Variables
Add HOOKRELAY_API_KEY with your key value
Select the environments (Production, Preview, Development)

Other Platforms#

Follow your platform’s documentation for setting environment variables:

Netlify: Site settings → Environment variables
Railway: Project settings → Variables
Render: Environment → Environment Variables

API Key vs HookRelay Secret#

It’s important to understand the difference:

API Key#

Purpose: Authenticate API requests to HookRelay
Used for: Managing endpoints, viewing events, etc.
Where: In API requests to api.hookrelay.io
Format: hr_live_...

HookRelay Secret#

Purpose: Verify webhooks forwarded to your Next.js app
Used for: Signature verification in your webhook handlers
Where: In your Next.js app as HOOKRELAY_SECRET
Format: hr_secret_...

You need both:

API Key for programmatic access to the HookRelay API
HookRelay Secret for verifying webhooks in your Next.js handlers

Common Use Cases#

CI/CD Integration#

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Create HookRelay Endpoint
        run: |
          curl -X POST https://api.hookrelay.io/v1/endpoints \
            -H "Authorization: Bearer ${{ secrets.HOOKRELAY_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "provider": "stripe",
              "forwardUrl": "https://myapp.com/api/webhooks/stripe"
            }'

Monitoring Script#

// scripts/check-webhook-health.ts
async function checkWebhookHealth() {
  const response = await fetch('https://api.hookrelay.io/v1/events', {
    headers: {
      Authorization: `Bearer ${process.env.HOOKRELAY_API_KEY}`,
    },
  });

  const events = await response.json();

  const failedEvents = events.items.filter((e: any) => e.status === 'failed');

  if (failedEvents.length > 0) {
    console.error(`Found ${failedEvents.length} failed events`);
    // Send alert
  }
}

Automated Endpoint Management#

// scripts/sync-endpoints.ts
async function syncEndpoints() {
  // Get all endpoints
  const response = await fetch('https://api.hookrelay.io/v1/endpoints', {
    headers: {
      Authorization: `Bearer ${process.env.HOOKRELAY_API_KEY}`,
    },
  });

  const endpoints = await response.json();

  // Update forward URLs based on environment
  for (const endpoint of endpoints.items) {
    const newUrl = getForwardUrlForEnvironment(endpoint.provider);

    await fetch(`https://api.hookrelay.io/v1/endpoints/${endpoint.id}`, {
      method: 'PATCH',
      headers: {
        Authorization: `Bearer ${process.env.HOOKRELAY_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        forwardUrl: newUrl,
      }),
    });
  }
}

Troubleshooting#

”Invalid API key” error#

Possible causes:

API key is incorrect or mistyped
API key was revoked
Missing “Bearer ” prefix in Authorization header

Solution:

Verify the key in the Settings page
Check that you’re using Bearer prefix: Authorization: Bearer hr_live_...
Create a new key if the old one was revoked

”API key not found” error#

Possible causes:

API key was deleted
Wrong API key is being used

Solution:

Check the Settings page to verify the key exists
Verify you’re using the correct key in your code
Create a new key if needed

Key not working in production#

Possible causes:

Environment variable not set in production
Different key used in different environments

Solution:

Verify the environment variable is set in your production environment
Check that you’re using the correct key for the environment
Use secret management to ensure keys are properly configured

Rate Limits#

API keys are subject to rate limits to ensure fair usage. Current limits:

Free: 100 requests per minute
Pro: 1,000 requests per minute
Team: 10,000 requests per minute

If you exceed the rate limit, you’ll receive a 429 Too Many Requests response. Implement exponential backoff when retrying.

Next Steps#

Learn about the HookRelay API (when available)
Review Best Practices for production deployments
Check out Getting Started for basic setup