API Keys

API keys provide secure programmatic access to Webhook Tester. Use them for CI/CD pipelines, automation scripts, or third-party integrations.

Key Features

• Programmatic Access: Create sessions and retrieve webhooks via API
• Scoped Permissions: Choose read, write, or admin level access
• Secure Storage: Keys are SHA-256 hashed before storage
• Expiration Control: Set custom expiry dates (default: 365 days)

Creating an API Key

1. Log in to your account
2. Navigate to API Keys page
3. Click Create API Key
4. Configure the key:
   • Name: Descriptive label (e.g., “CI/CD Pipeline”)
   • Permissions: Select access level
   • Expires: Choose expiration date
5. Click Create

You’ll see the full key once:

whpk_live_K7nR9qZ3mX8vL2pY5wT4jH6cF1bN0dS3

Important: Copy the key immediately! You won’t be able to see it again.

Key Format

API keys follow this format:

• Prefix: whpk_live_ (identifies as Webhook Tester key)
• Body: 32 random bytes (base64url encoded)
• Total length: ~50 characters

Permission Levels

Permission levels are cumulative:

• write includes all read permissions
• admin includes all write + read permissions

Using API Keys

Authentication

Include the key in the Authorization header:

curl -X POST https://webhook-tester.appfactory.workers.dev/api/sessions \
  -H "Authorization: Api-Key whpk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Session"}'

Create Session

curl -X POST https://webhook-tester.appfactory.workers.dev/api/sessions \
  -H "Authorization: Api-Key whpk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Session",
    "settings": {
      "auto_cleanup": true,
      "max_age_hours": 24
    }
  }'

Response:

{
  "id": "session-id",
  "name": "CI/CD Session",
  "webhook_url": "https://webhook-tester.appfactory.workers.dev/api/webhook/session-id"
}

Retrieve Webhooks

curl https://webhook-tester.appfactory.workers.dev/api/sessions/{session-id}/requests \
  -H "Authorization: Api-Key whpk_live_your_key_here"

Revoking API Keys

To revoke a key:

1. Go to API Keys page
2. Find the key in the list
3. Click Revoke

The key is immediately invalidated. Any scripts using it will receive 401 Unauthorized.

Best Practices

Security

• ✅ Store keys in environment variables, never in code
• ✅ Use minimal required permissions
• ✅ Rotate keys regularly (every 90 days)
• ✅ Revoke keys immediately if compromised
• ❌ Never commit keys to git repositories
• ❌ Never share keys in chat or email

Naming Conventions

Use descriptive names that identify the key’s purpose:

• ✅ prod-github-actions
• ✅ staging-tests
• ✅ dev-macbook
• ❌ key1
• ❌ test

CI/CD Integration

For GitHub Actions, store the key as a repository secret:

1. Go to Settings → Secrets and variables → Actions
2. Add secret: WEBHOOK_TESTER_API_KEY
3. Use in workflow:

steps:
  - name: Create webhook session
    env:
      API_KEY: ${{ secrets.WEBHOOK_TESTER_API_KEY }}
    run: |
      curl -X POST https://webhook-tester.appfactory.workers.dev/api/sessions \
        -H "Authorization: Api-Key $API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"name": "CI Build ${{ github.run_id }}"}'

Rate Limits

API keys are subject to standard rate limits:

• 100 requests/minute per key
• 422 Unsupported Media Type: Rate limit exceeded includes retry-after header

Troubleshooting

Invalid Key Error

401 Unauthorized: Invalid API key

Solution: Verify the key hasn’t been revoked. Create a new key if needed.

Permission Denied

403 Forbidden: Insufficient permissions

Solution: Your key lacks the required permission level. Create a new key with appropriate permissions.

Key Not Found

404 Not Found: API key not found

Solution: Ensure you’re using the full key including whpk_live_ prefix.