Endpoints API

The Endpoints API allows you to create, list, update, and delete webhook endpoints.

Authentication

All endpoints in this section require JWT Bearer authentication:

Authorization: Bearer <JWT_TOKEN>

Endpoint Object

Copy
{
  "id": "cm1a2b3c4d5e6f7g8h9i0j1k",
  "name": "My Webhook",
  "slug": "my-webhook",
  "description": "Receives Stripe payment events",
  "isActive": true,
  "userId": "user_abc123",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "url": "https://hooksdash.ibadsiddiqui.dev/api/h/my-webhook"
}

Attributes

API Endpoints

Create Endpoint

Creates a new webhook endpoint.

Copy
POST /api/endpoints

Headers:

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

Request Body:

Copy
{
  "name": "My Webhook",
  "slug": "my-webhook",
  "description": "Receives Stripe payment events"
}

Parameters:

Slug Requirements:

• 3-50 characters
• Lowercase letters, numbers, and hyphens only
• Cannot start or end with a hyphen
• Must be unique across all endpoints

Response:

Copy
{
  "id": "cm1a2b3c4d5e6f7g8h9i0j1k",
  "name": "My Webhook",
  "slug": "my-webhook",
  "description": "Receives Stripe payment events",
  "isActive": true,
  "userId": "user_abc123",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Status Codes:

• 201 Created - Endpoint created successfully
• 400 Bad Request - Validation error
• 403 Forbidden - Endpoint limit reached for your tier
• 409 Conflict - Slug already in use
• 401 Unauthorized - Invalid or missing authentication

Example:

Copy
curl -X POST https://hooksdash-api.ibadsiddiqui.dev/api/endpoints \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Webhook",
    "description": "Receives Stripe payment events"
  }'

Validation Errors:

Copy
{
  "statusCode": 400,
  "message": [
    "name must be longer than or equal to 1 characters",
    "slug must match the required pattern"
  ],
  "error": "Bad Request"
}

---

List Endpoints

Retrieves a paginated list of your endpoints with statistics.

Copy
GET /api/endpoints

Headers:

Authorization: Bearer <JWT_TOKEN>

Query Parameters:

Response:

Copy
{
  "data": [
    {
      "id": "cm1a2b3c4d5e6f7g8h9i0j1k",
      "name": "My Webhook",
      "slug": "my-webhook",
      "description": "Receives Stripe payment events",
      "isActive": true,
      "userId": "user_abc123",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "_count": {
        "requests": 42
      },
      "lastRequest": {
        "id": "req_xyz789",
        "createdAt": "2024-01-15T14:25:00.000Z"
      }
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Status Codes:

• 200 OK - Endpoints returned
• 401 Unauthorized - Invalid or missing authentication

Example:

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

---

Get Endpoint

Retrieves a specific endpoint by ID with detailed statistics.

Copy
GET /api/endpoints/:id

Headers:

Authorization: Bearer <JWT_TOKEN>

Parameters:

• id (path) - The endpoint ID

Response:

Copy
{
  "id": "cm1a2b3c4d5e6f7g8h9i0j1k",
  "name": "My Webhook",
  "slug": "my-webhook",
  "description": "Receives Stripe payment events",
  "isActive": true,
  "userId": "user_abc123",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "_count": {
    "requests": 42
  },
  "lastRequest": {
    "id": "req_xyz789",
    "method": "POST",
    "path": "/webhook",
    "createdAt": "2024-01-15T14:25:00.000Z"
  }
}

Status Codes:

• 200 OK - Endpoint 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 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Update Endpoint

Updates an existing endpoint. Only provided fields will be updated.

Copy
PUT /api/endpoints/:id

Headers:

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

Parameters:

• id (path) - The endpoint ID

Request Body:

Copy
{
  "name": "Updated Webhook Name",
  "description": "Updated description",
  "isActive": false
}

Body Parameters:

Note: The slug cannot be updated after creation.

Response:

Copy
{
  "id": "cm1a2b3c4d5e6f7g8h9i0j1k",
  "name": "Updated Webhook Name",
  "slug": "my-webhook",
  "description": "Updated description",
  "isActive": false,
  "userId": "user_abc123",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T15:45:00.000Z"
}

Status Codes:

• 200 OK - Endpoint updated
• 400 Bad Request - Validation error
• 404 Not Found - Endpoint not found or not owned by user
• 401 Unauthorized - Invalid or missing authentication

Example:

Copy
curl -X PUT https://hooksdash-api.ibadsiddiqui.dev/api/endpoints/cm1a2b3c4d5e6f7g8h9i0j1k \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

---

Delete Endpoint

Deletes an endpoint and all associated requests.

⚠️ Warning: This action is irreversible. All requests for this endpoint will be permanently deleted.

Copy
DELETE /api/endpoints/:id

Headers:

Authorization: Bearer <JWT_TOKEN>

Parameters:

• id (path) - The endpoint ID

Response:

Copy
{
  "deleted": true
}

Status Codes:

• 200 OK - Endpoint deleted
• 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 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Endpoint States

Active vs Inactive

Endpoints can be active or inactive:

• Active (isActive: true): Receives and stores webhook requests
• Inactive (isActive: false): Rejects webhook requests with 403 Forbidden

You can toggle this state using the Update Endpoint endpoint.

Automatic Deactivation

Endpoints are automatically deactivated when:

• Rate limit is consistently exceeded
• Endpoint hasn't received requests in 90 days (Pro and below)

Enterprise accounts have no automatic deactivation.

Tier Limits

Maximum number of endpoints by tier:

When you reach your tier limit, you'll receive a 403 Forbidden error when trying to create new endpoints:

Copy
{
  "statusCode": 403,
  "message": "Endpoint limit reached for your tier. Please upgrade to create more endpoints.",
  "error": "Forbidden"
}

Slug Generation

If you don't provide a custom slug, one will be auto-generated from the endpoint name:

1. Convert to lowercase
2. Replace spaces and special characters with hyphens
3. Remove consecutive hyphens
4. Add a random suffix if needed to ensure uniqueness

Examples:

• "My Webhook" → my-webhook
• "Stripe Payment Events" → stripe-payment-events
• "GitHub PR Notifications" → github-pr-notifications-a1b2

Use Cases

Development & Testing

Copy
# Create a test endpoint
curl -X POST https://hooksdash-api.ibadsiddiqui.dev/api/endpoints \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development Test",
    "slug": "dev-test"
  }'

# Use the webhook URL in your tests
# POST https://hooksdash.ibadsiddiqui.dev/api/h/dev-test

Production Webhooks

Copy
# Create a production endpoint
curl -X POST https://hooksdash-api.ibadsiddiqui.dev/api/endpoints \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe Production",
    "slug": "stripe-prod",
    "description": "Receives Stripe webhooks for production environment"
  }'

# Configure in Stripe dashboard:
# https://hooksdash.ibadsiddiqui.dev/api/h/stripe-prod

Temporary Endpoints

Copy
# Create endpoint
ENDPOINT_ID=$(curl -X POST https://hooksdash-api.ibadsiddiqui.dev/api/endpoints \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Temp Test"}' | jq -r '.id')

# Use endpoint...

# Delete when done
curl -X DELETE https://hooksdash-api.ibadsiddiqui.dev/api/endpoints/$ENDPOINT_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Best Practices

1. Use descriptive names: Include the service name and environment (e.g., "Stripe Production", "GitHub Staging")

2. Set descriptions: Document what each endpoint receives for future reference

3. Use custom slugs: For production endpoints, use meaningful slugs instead of auto-generated ones

4. Deactivate unused endpoints: Set isActive: false instead of deleting if you might need them later

5. Monitor request counts: Use the list endpoint to check which endpoints are actively receiving requests

6. Clean up old endpoints: Delete endpoints you no longer need to stay within tier limits