Requests API

The Requests API allows you to inspect, replay, and manage webhook requests captured by your endpoints.

Authentication

All endpoints in this section require JWT Bearer authentication:

Authorization: Bearer <JWT_TOKEN>

Request Object

Copy
{
  "id": "req_cm1a2b3c4d5e6f7g8h9i0j1k",
  "endpointId": "cm1a2b3c4d5e6f7g8h9i0j1k",
  "method": "POST",
  "path": "/webhook",
  "query": {
    "utm_source": "email",
    "campaign_id": "123"
  },
  "headers": {
    "content-type": "application/json",
    "user-agent": "Stripe/1.0",
    "x-stripe-signature": "t=1234567890,v1=..."
  },
  "body": {
    "event": "payment_intent.succeeded",
    "data": {
      "object": {
        "id": "pi_123",
        "amount": 5000
      }
    }
  },
  "ip": "192.168.1.100",
  "userAgent": "Stripe/1.0",
  "createdAt": "2024-01-15T14:25:00.000Z"
}

Attributes

API Endpoints

List Requests for Endpoint

Retrieves a paginated list of requests for a specific endpoint.

Copy
GET /api/endpoints/:endpointId/requests

Headers:

Authorization: Bearer <JWT_TOKEN>

Parameters:

• endpointId (path) - The endpoint ID

Query Parameters:

Response:

Copy
{
  "data": [
    {
      "id": "req_cm1a2b3c4d5e6f7g8h9i0j1k",
      "endpointId": "cm1a2b3c4d5e6f7g8h9i0j1k",
      "method": "POST",
      "path": "/webhook",
      "query": {},
      "headers": {
        "content-type": "application/json"
      },
      "body": {
        "event": "test"
      },
      "ip": "192.168.1.100",
      "userAgent": "Mozilla/5.0",
      "createdAt": "2024-01-15T14:25:00.000Z"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

Status Codes:

• 200 OK - Requests returned
• 404 Not Found - Endpoint not found or not owned by user
• 401 Unauthorized - Invalid or missing authentication

Example:

Copy
curl -X GET "https://hooksdash-api.ibadsiddiqui.dev/api/endpoints/cm1a2b3c4d5e6f7g8h9i0j1k/requests?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Get Request

Retrieves a specific request by ID with full details.

Copy
GET /api/requests/:id

Headers:

Authorization: Bearer <JWT_TOKEN>

Parameters:

• id (path) - The request ID

Response:

Copy
{
  "id": "req_cm1a2b3c4d5e6f7g8h9i0j1k",
  "endpointId": "cm1a2b3c4d5e6f7g8h9i0j1k",
  "method": "POST",
  "path": "/webhook",
  "query": {
    "source": "api"
  },
  "headers": {
    "content-type": "application/json",
    "user-agent": "Stripe/1.0",
    "x-stripe-signature": "t=1234567890,v1=..."
  },
  "body": {
    "event": "payment_intent.succeeded",
    "data": {
      "object": {
        "id": "pi_123",
        "amount": 5000,
        "currency": "usd"
      }
    }
  },
  "ip": "54.187.216.72",
  "userAgent": "Stripe/1.0",
  "createdAt": "2024-01-15T14:25:00.000Z"
}

Status Codes:

• 200 OK - Request returned
• 404 Not Found - Request not found or not owned by user
• 401 Unauthorized - Invalid or missing authentication

Example:

Copy
curl -X GET https://hooksdash-api.ibadsiddiqui.dev/api/requests/req_cm1a2b3c4d5e6f7g8h9i0j1k \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Replay Request

Forwards a captured request to a different URL, optionally overriding request properties.

Copy
POST /api/requests/:id/replay

Headers:

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

Parameters:

• id (path) - The request ID to replay

Request Body:

Copy
{
  "url": "https://example.com/webhook",
  "method": "POST",
  "headers": {
    "x-custom-header": "custom-value"
  },
  "body": {
    "overridden": true
  }
}

Body Parameters:

Note: If not provided, method, headers, and body will use the values from the original request.

Response:

Copy
{
  "success": true,
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "application/json",
    "x-request-id": "abc123"
  },
  "body": {
    "received": true,
    "id": "evt_123"
  },
  "duration": 245
}

Response Attributes:

Status Codes:

• 200 OK - Replay completed (check success field for actual result)
• 404 Not Found - Request not found or not owned by user
• 400 Bad Request - Invalid URL or request parameters
• 401 Unauthorized - Invalid or missing authentication

Example:

Copy
curl -X POST https://hooksdash-api.ibadsiddiqui.dev/api/requests/req_cm1a2b3c4d5e6f7g8h9i0j1k/replay \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook"
  }'

Replay with overrides:

Copy
curl -X POST https://hooksdash-api.ibadsiddiqui.dev/api/requests/req_cm1a2b3c4d5e6f7g8h9i0j1k/replay \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://localhost:3000/webhook",
    "method": "POST",
    "headers": {
      "x-test-mode": "true"
    }
  }'

---

Delete Request

Deletes a specific request.

Copy
DELETE /api/requests/:id

Headers:

Authorization: Bearer <JWT_TOKEN>

Parameters:

• id (path) - The request ID

Response:

Copy
{
  "deleted": true
}

Status Codes:

• 200 OK - Request deleted
• 404 Not Found - Request not found or not owned by user
• 401 Unauthorized - Invalid or missing authentication

Example:

Copy
curl -X DELETE https://hooksdash-api.ibadsiddiqui.dev/api/requests/req_cm1a2b3c4d5e6f7g8h9i0j1k \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Delete All Requests for Endpoint

Deletes all requests for a specific endpoint.

⚠️ Warning: This action is irreversible.

Copy
DELETE /api/endpoints/:endpointId/requests

Headers:

Authorization: Bearer <JWT_TOKEN>

Parameters:

• endpointId (path) - The endpoint ID

Response:

Copy
{
  "deleted": 42
}

Status Codes:

• 200 OK - Requests deleted (returns count)
• 404 Not Found - Endpoint not found or not owned by user
• 401 Unauthorized - Invalid or missing authentication

Example:

Copy
curl -X DELETE https://hooksdash-api.ibadsiddiqui.dev/api/endpoints/cm1a2b3c4d5e6f7g8h9i0j1k/requests \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Request Storage & Retention

Storage Limits

Maximum requests stored per endpoint by tier:

When the limit is reached, the oldest requests are automatically deleted (FIFO).

Retention Period

Requests are automatically deleted after:

Request Replay

Use Cases

1. Local Development: Replay production webhooks to your local development server

Copy
# Start local server
npm run dev

# Replay webhook to localhost
curl -X POST https://hooksdash-api.ibadsiddiqui.dev/api/requests/req_xyz/replay \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "http://localhost:3000/webhook"}'

1. Testing: Replay webhooks to staging environments

Copy
curl -X POST https://hooksdash-api.ibadsiddiqui.dev/api/requests/req_xyz/replay \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://staging.example.com/webhook"}'

1. Debugging: Replay with modified data to test edge cases

Copy
curl -X POST https://hooksdash-api.ibadsiddiqui.dev/api/requests/req_xyz/replay \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://localhost:3000/webhook",
    "body": {
      "amount": 999999,
      "test_case": "large_amount"
    }
  }'

Security Considerations

• Replay requests are sent from HooksDash servers, not from the original source
• The X-Forwarded-For header will contain the original request IP
• Signature headers (like X-Stripe-Signature) are preserved but may be invalid if the body is modified
• Only replay to URLs you control and trust

Replay Errors

Common error responses:

Copy
{
  "success": false,
  "error": "Connection refused",
  "duration": 1000
}

Copy
{
  "success": false,
  "status": 500,
  "statusText": "Internal Server Error",
  "error": "Target server error",
  "duration": 532
}

Filtering & Searching

Filter by Method

Copy
# Get all POST requests
curl -X GET "https://hooksdash-api.ibadsiddiqui.dev/api/endpoints/cm1a2b3c4d5e6f7g8h9i0j1k/requests" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  | jq '.data[] | select(.method == "POST")'

Filter by IP

Copy
# Get requests from specific IP
curl -X GET "https://hooksdash-api.ibadsiddiqui.dev/api/endpoints/cm1a2b3c4d5e6f7g8h9i0j1k/requests" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  | jq '.data[] | select(.ip == "54.187.216.72")'

Search Body Content

Copy
# Search for requests containing specific event
curl -X GET "https://hooksdash-api.ibadsiddiqui.dev/api/endpoints/cm1a2b3c4d5e6f7g8h9i0j1k/requests" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  | jq '.data[] | select(.body.event == "payment_intent.succeeded")'

Best Practices

1. Regularly clean up old requests: Delete requests you no longer need to free up storage

2. Use pagination: Don't request all requests at once; use pagination for better performance

3. Replay selectively: Don't replay all requests; select specific ones for testing

4. Preserve original data: When replaying, avoid modifying the request unless necessary for testing

5. Monitor retention: Be aware of your tier's retention period and export important requests before they expire

6. Use filters: Filter requests client-side after fetching to find specific patterns

Request Analysis

Understanding Headers

Common headers you'll see in webhook requests:

• content-type: Format of the request body (application/json, application/xml, etc.)
• user-agent: Client that sent the request
• x-forwarded-for: Original client IP (if proxied)
• Signature headers: Webhook signature for verification (e.g., x-stripe-signature, x-hub-signature)

Body Formats

Request bodies can be:

• JSON object: Most common for modern webhooks
• JSON array: Less common but possible
• String: For form data, XML, or plain text
• null: For GET requests or requests without a body

Query Parameters

Query parameters are stored separately from the path and body:

Copy
{
  "path": "/webhook",
  "query": {
    "source": "api",
    "version": "2"
  }
}

Full URL would be: https://hooksdash.ibadsiddiqui.dev/api/h/your-slug/webhook?source=api&version=2