Debug Endpoints

Debug Endpoints are Organization-owned, permanent webhook testing endpoints for inspecting and debugging webhook integrations. Unlike Anonymous Endpoints, Debug Endpoints persist indefinitely, support team collaboration, and integrate with the full Hooklistener platform.

Overview

Debug Endpoints provide a permanent URL for testing webhook integrations. Send webhooks to the URL and view them instantly in the dashboard, complete with headers, body, and metadata. Perfect for ongoing development, QA testing, and debugging production issues.

Key features:

Permanent endpoints: No expiration, persist until deleted
Organization-owned: Full team access with role-based permissions
Unlimited webhooks: No artificial limits on webhook volume
Real-time inspection: View webhooks instantly in dashboard
WebSocket streaming: Live updates for active debugging sessions
Search and filter: Find specific webhooks quickly
Custom slugs: Memorable, human-readable endpoint URLs
Pause/resume: Temporarily disable endpoints without deleting

When to Use

Perfect For:

Development and Testing:

Ongoing webhook integration development
QA and staging environment testing
Integration testing in CI/CD pipelines
Debugging webhook-related issues

Team Collaboration:

Shared testing endpoints across team
Role-based access control
Persistent webhook history
Team debugging sessions

Long-term Debugging:

Permanent webhook inspection URLs
Historical webhook data
Issue reproduction
Integration monitoring

Debug Endpoints vs Anonymous Endpoints

Feature	Debug Endpoints	Anonymous Endpoints
Duration	Permanent	Temporary (max 7 days)
Authentication	Required (API key)	None
Team Access	Role-based	Token-based
Webhook Limit	Based on plan	1,000 max
Retention	Based on plan	Until expiration
Custom Slugs	Yes	No
Pause/Resume	Yes	No
Forwarding	Future feature	No

Use Debug Endpoints for: Production-grade testing, team collaboration, permanent debugging

Use Anonymous Endpoints for: Quick tests, evaluation, no-account testing

How It Works

Endpoint Lifecycle

Create endpoint:
- Choose name and optional slug
- Endpoint created under your Organization
- Receive unique webhook URL
Send webhooks:
- POST requests to webhook URL
- All HTTP methods supported
- Any payload format accepted
View and manage:
- Real-time webhook inspection in dashboard
- Search, filter, and analyze webhooks
- Pause/resume endpoint as needed
Delete when done:
- Manual deletion only
- All associated webhooks deleted
- Cannot be undone

URL Format

Debug Endpoint URLs use slugs for readability:

https://api.hooklistener.com/debug/{slug}

Example:

https://api.hooklistener.com/debug/stripe-dev
https://api.hooklistener.com/debug/github-webhook-test
https://api.hooklistener.com/debug/payment-staging

Slugs are globally unique across all Hooklistener organizations.

Creating Debug Endpoints

Via Dashboard

Step 1: Navigate to Debug Endpoints

Go to Debug section in sidebar
Click "Create Debug Endpoint"

Step 2: Configure Endpoint

Name: Descriptive name for the endpoint
- Example: "Stripe Development", "GitHub Staging", "Payment Webhook Testing"
Slug (optional): Custom URL path
- Auto-generated from name if not provided
- Must be unique globally
- Lowercase letters, numbers, and hyphens only
- Example: stripe-dev, github-staging, payment-test
Click "Create"

Step 3: Get Webhook URL

Copy the webhook URL:

https://api.hooklistener.com/debug/your-slug

Via API

Create endpoint:

curl -X POST https://api.hooklistener.com/api/v1/debug-endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "debug_endpoint": {
      "name": "Stripe Development",
      "slug": "stripe-dev"
    }
  }'

Response:

{
  "id": "dbg_abc123def456",
  "name": "Stripe Development",
  "slug": "stripe-dev",
  "status": "active",
  "webhook_url": "https://api.hooklistener.com/debug/stripe-dev",
  "organization_id": "org_xyz789",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Create with auto-generated slug:

curl -X POST https://api.hooklistener.com/api/v1/debug-endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "debug_endpoint": {
      "name": "Payment Testing"
    }
  }'

Slug will be generated from name: payment-testing-xyz

Sending Webhooks

Send webhooks to your Debug Endpoint URL:

Basic Request

curl -X POST https://api.hooklistener.com/debug/stripe-dev \
  -H "Content-Type: application/json" \
  -d '{
    "event": "payment.succeeded",
    "amount": 1000,
    "currency": "usd"
  }'

With Headers

curl -X POST https://api.hooklistener.com/debug/stripe-dev \
  -H "Content-Type: application/json" \
  -H "X-Stripe-Signature: t=1234567890,v1=abc..." \
  -H "X-Request-ID: req_12345" \
  -d '{
    "id": "evt_12345",
    "type": "payment_intent.succeeded"
  }'

Different Methods

# GET with query parameters
curl -X GET "https://api.hooklistener.com/debug/stripe-dev?param=value&test=true"

# PUT request
curl -X PUT https://api.hooklistener.com/debug/stripe-dev \
  -d '{"status": "updated"}'

# PATCH request
curl -X PATCH https://api.hooklistener.com/debug/stripe-dev \
  -d '{"partial": "update"}'

# DELETE request
curl -X DELETE https://api.hooklistener.com/debug/stripe-dev

Response

All webhook requests receive:

{
  "message": "Webhook captured successfully",
  "request_id": "req_xyz789"
}

HTTP 200 OK - Webhook received and stored HTTP 404 Not Found - Endpoint slug doesn't exist HTTP 429 Too Many Requests - Rate limit exceeded

Viewing Webhooks

Via Dashboard

Access endpoint:

Navigate to Debug → Endpoints
Click on your endpoint
View webhook list in real-time

Webhook details include:

Timestamp (when received)
HTTP method
Headers (all request headers)
Body (formatted JSON or raw)
Response status
Request ID

Features:

Real-time updates (new webhooks appear automatically)
Syntax highlighting for JSON
Copy webhook details
Search and filter
Pagination

Via API

List endpoints:

curl -X GET https://api.hooklistener.com/api/v1/debug-endpoints \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "debug_endpoints": [
    {
      "id": "dbg_abc123",
      "name": "Stripe Development",
      "slug": "stripe-dev",
      "status": "active",
      "webhook_url": "https://api.hooklistener.com/debug/stripe-dev",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "dbg_def456",
      "name": "GitHub Staging",
      "slug": "github-staging",
      "status": "paused",
      "webhook_url": "https://api.hooklistener.com/debug/github-staging",
      "created_at": "2024-01-14T09:15:00Z"
    }
  ]
}

Get specific endpoint:

curl -X GET https://api.hooklistener.com/api/v1/debug-endpoints/{endpoint_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

List webhooks for endpoint:

curl -X GET "https://api.hooklistener.com/api/v1/debug-endpoints/{endpoint_id}/requests?page=1&page_size=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "debug_requests": [
    {
      "id": "req_xyz789",
      "debug_endpoint_id": "dbg_abc123",
      "method": "POST",
      "headers": {
        "content-type": "application/json",
        "x-stripe-signature": "t=1234567890,v1=abc..."
      },
      "body": "{\"event\":\"payment.succeeded\",\"amount\":1000}",
      "status": "200",
      "created_at": "2024-01-15T10:35:22Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_count": 127,
    "total_pages": 3
  }
}

Get specific webhook:

curl -X GET https://api.hooklistener.com/api/v1/debug-endpoints/{endpoint_id}/requests/{request_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Managing Endpoints

Pausing Endpoints

Temporarily disable an endpoint without deleting webhooks:

Via Dashboard:

Go to endpoint details
Click "Pause Endpoint"
Webhooks sent while paused receive 404

Via API:

curl -X PATCH https://api.hooklistener.com/api/v1/debug-endpoints/{endpoint_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "debug_endpoint": {
      "status": "paused"
    }
  }'

Resuming Endpoints

Re-enable a paused endpoint:

Via Dashboard:

Go to endpoint details
Click "Resume Endpoint"

Via API:

curl -X PATCH https://api.hooklistener.com/api/v1/debug-endpoints/{endpoint_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "debug_endpoint": {
      "status": "active"
    }
  }'

Renaming Endpoints

Update endpoint name (slug cannot be changed):

Via Dashboard:

Go to endpoint details
Click "Edit"
Update name
Click "Save"

Via API:

curl -X PATCH https://api.hooklistener.com/api/v1/debug-endpoints/{endpoint_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "debug_endpoint": {
      "name": "Stripe Production Testing"
    }
  }'

Deleting Endpoints

Permanently delete endpoint and all webhooks:

Via Dashboard:

Go to endpoint details
Click "Delete Endpoint"
Confirm deletion
Cannot be undone

Via API:

curl -X DELETE https://api.hooklistener.com/api/v1/debug-endpoints/{endpoint_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: HTTP 204 No Content

Real-Time Updates

WebSocket Connection

Subscribe to live webhook notifications:

Connect to endpoint channel:

import { Socket } from 'phoenix';

const socket = new Socket('wss://api.hooklistener.com/socket', {
  params: { token: 'YOUR_API_KEY' }
});

socket.connect();

const channel = socket.channel(`debug:${endpointId}`, {});

channel.on('webhook_received', (payload) => {
  console.log('New webhook:', payload);
  // Update UI with new webhook
});

channel.join()
  .receive('ok', () => console.log('Joined debug channel'))
  .receive('error', (resp) => console.error('Join failed:', resp));

Webhook event payload:

{
  "request_id": "req_xyz789",
  "endpoint_id": "dbg_abc123",
  "method": "POST",
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"event\":\"test\"}",
  "status": "200",
  "timestamp": "2024-01-15T10:35:22Z"
}

Use Cases

Development Environment Testing

Setup:

Create separate debug endpoints per environment:

# Development
curl -X POST https://api.hooklistener.com/api/v1/debug-endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"debug_endpoint": {"name": "Stripe Dev", "slug": "stripe-dev"}}'

# Staging
curl -X POST https://api.hooklistener.com/api/v1/debug-endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"debug_endpoint": {"name": "Stripe Staging", "slug": "stripe-staging"}}'

# Production Testing
curl -X POST https://api.hooklistener.com/api/v1/debug-endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"debug_endpoint": {"name": "Stripe Prod Test", "slug": "stripe-prod-test"}}'

Configure providers:

Point each environment to its debug endpoint
Test in isolation
Monitor webhooks per environment

CI/CD Integration Testing

In your test suite:

// test/integration/webhooks.test.js
const axios = require('axios');

describe('Webhook Integration', () => {
  const DEBUG_ENDPOINT = 'https://api.hooklistener.com/debug/ci-test-webhooks';

  it('should send webhook with correct format', async () => {
    // Trigger webhook in your application
    await triggerWebhookEvent();

    // Wait for webhook to arrive
    await new Promise(resolve => setTimeout(resolve, 2000));

    // Verify webhook was received
    const response = await axios.get(
      `https://api.hooklistener.com/api/v1/debug-endpoints/${endpointId}/requests`,
      {
        headers: { Authorization: `Bearer ${process.env.HOOKLISTENER_API_KEY}` }
      }
    );

    expect(response.data.debug_requests).toHaveLength(1);
    expect(response.data.debug_requests[0].body).toMatchObject({
      event: 'order.created',
      orderId: expect.any(String)
    });
  });
});

Production Issue Debugging

Scenario: Debug production webhook issues

1. Create temporary debug endpoint:

curl -X POST https://api.hooklistener.com/api/v1/debug-endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"debug_endpoint": {"name": "Prod Issue Debug", "slug": "prod-debug-jan-15"}}'

2. Temporarily route production webhooks to debug endpoint

3. Inspect webhooks in dashboard:

Verify payload structure
Check headers (signatures, IDs, etc.)
Identify issues

4. Fix issue in production

5. Delete debug endpoint:

curl -X DELETE https://api.hooklistener.com/api/v1/debug-endpoints/dbg_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Team Collaboration

Shared endpoint for team:

Admin creates debug endpoint
All team members can:
- View webhooks in dashboard
- Use endpoint in development
- Debug issues together
Role-based permissions apply:
- Members: View webhooks
- Admins: Create/delete endpoints
- Owners: Full access

Plan Limits

Debug Endpoint limits vary by plan:

Free Plan

Endpoints: 3
Retention: 7 days
Features: Basic inspection

Team Plan

Endpoints: 10
Retention: 30 days
Features: Full access, WebSocket

Enterprise Plan

Endpoints: Unlimited
Retention: 90 days (configurable)
Features: All features, priority support

See Plans & Features for complete details.

Best Practices

Endpoint Organization

Use descriptive names:

✅ "Stripe Webhooks - Development"
✅ "GitHub PR Notifications - Staging"
✅ "Payment Processing - QA"

❌ "Test"
❌ "Endpoint 1"
❌ "My Webhook"

Use meaningful slugs:

✅ stripe-dev
✅ github-pr-staging
✅ payment-qa

❌ test1
❌ endpoint
❌ abc123

Endpoint Lifecycle

Create per environment:

One endpoint per environment (dev, staging, prod)
Separate endpoints for different webhook providers
Temporary endpoints for debugging

Pause instead of delete:

Pause endpoints when not actively using
Preserves webhooks for later review
Easy to resume

Clean up regularly:

Delete old debugging endpoints
Remove unused test endpoints
Keep endpoint list manageable

Security

Protect API keys:

Never commit API keys to source control
Use environment variables
Rotate keys regularly

Review webhook data:

Don't send sensitive production data to debug endpoints
Use test data when possible
Clear webhooks containing sensitive info

Monitor access:

Review team member access
Remove access when team members leave
Audit endpoint usage

Troubleshooting

Endpoint Not Found (404)

Causes:

Slug doesn't exist
Slug typo
Endpoint deleted

Solution:

Verify slug in dashboard
Check endpoint list via API
Recreate if deleted

Webhooks Not Appearing

Causes:

Endpoint paused
Webhook sent to wrong URL
Network issues

Solution:

Check endpoint status (active vs paused)
Verify webhook URL
Test with curl

Cannot Create Endpoint

Causes:

Reached plan limit
Slug already taken
Invalid slug format

Solution:

# Check current endpoint count
curl -X GET https://api.hooklistener.com/api/v1/debug-endpoints \
  -H "Authorization: Bearer YOUR_API_KEY"

# Use different slug
# Verify slug format: lowercase, numbers, hyphens only

Webhook Limit Reached (429)

Causes:

Too many webhooks per minute
Rate limit exceeded

Solution:

Implement exponential backoff
Reduce webhook frequency
Upgrade plan for higher limits

Next Steps

Now that you understand Debug Endpoints:

Create your first debug endpoint - Follow the guide above
Try Anonymous Endpoints - For quick tests without account
Build Bridges - For production webhook workflows
Review Plans - Find the right plan for your needs

Debug Endpoints are essential for webhook development and testing. Use them throughout your development lifecycle for reliable, permanent webhook inspection.

Overview​

When to Use​

Perfect For:​

Debug Endpoints vs Anonymous Endpoints​

How It Works​

Endpoint Lifecycle​

URL Format​

Creating Debug Endpoints​

Via Dashboard​

Via API​

Sending Webhooks​

Basic Request​

With Headers​

Different Methods​

Response​

Viewing Webhooks​

Via Dashboard​

Via API​

Managing Endpoints​

Pausing Endpoints​

Resuming Endpoints​

Renaming Endpoints​

Deleting Endpoints​

Real-Time Updates​

WebSocket Connection​

Use Cases​

Development Environment Testing​

CI/CD Integration Testing​

Production Issue Debugging​

Team Collaboration​

Plan Limits​

Free Plan​

Team Plan​

Enterprise Plan​

Best Practices​

Endpoint Organization​

Endpoint Lifecycle​

Security​

Troubleshooting​

Endpoint Not Found (404)​

Webhooks Not Appearing​

Cannot Create Endpoint​

Webhook Limit Reached (429)​

Next Steps​

Overview

When to Use

Perfect For:

Debug Endpoints vs Anonymous Endpoints

How It Works

Endpoint Lifecycle

URL Format

Creating Debug Endpoints

Via Dashboard

Via API

Sending Webhooks

Basic Request

With Headers

Different Methods

Response

Viewing Webhooks

Via Dashboard

Via API

Managing Endpoints

Pausing Endpoints

Resuming Endpoints

Renaming Endpoints

Deleting Endpoints

Real-Time Updates

WebSocket Connection

Use Cases

Development Environment Testing

CI/CD Integration Testing

Production Issue Debugging

Team Collaboration

Plan Limits

Free Plan

Team Plan

Enterprise Plan

Best Practices

Endpoint Organization

Endpoint Lifecycle

Security

Troubleshooting

Endpoint Not Found (404)

Webhooks Not Appearing

Cannot Create Endpoint

Webhook Limit Reached (429)

Next Steps