API Reference

API Reference

Complete reference for the Web Hook Box REST API.

API Base URL

All API requests should be made to: https://webhookbox.com/api/v1/

Web Hook Box provides a comprehensive RESTful API that allows you to programmatically create and manage webhook endpoints, access webhook request data, and more. This reference documents all available endpoints and their parameters.

API Features
  • Create, update, and delete webhook endpoints
  • Access webhook request data and metadata
  • Configure response behavior and request forwarding
  • Manage user account settings and API keys
  • Access usage statistics and logs

Authentication

All API requests require authentication using an API token.

Authentication Methods
Bearer Token (Recommended)

Include your API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN
Query Parameter

Alternatively, you can include the token as a query parameter:

https://webhookbox.com/api/v1/webhooks?token=YOUR_API_TOKEN
Security Note: Query parameter authentication is less secure as tokens may be logged in server logs.
Managing API Tokens

You can create and manage API tokens from your account settings page. We recommend creating separate tokens for different applications or services.

Security Best Practices
  • Keep your API tokens secure and never expose them in client-side code
  • Rotate tokens regularly and revoke unused ones
  • Set appropriate permissions for each token
  • Use separate tokens for development and production environments

API Endpoints Overview

The Web Hook Box API is organized around the following resource groups:

Resource Base Path Description
Webhooks /webhooks Create and manage webhook endpoints
Requests /webhooks/{id}/requests Access and manage webhook request data
User /user Manage user account settings
Tokens /tokens Manage API tokens
Tip: For code examples of common API operations, check out the Code Examples section.

Webhook API

These endpoints allow you to create and manage webhook endpoints.

List Webhooks
GET /webhooks

Retrieve a list of all webhooks for the authenticated user.

Query Parameters
  • page - Page number for pagination (default: 1)
  • limit - Number of results per page (default: 20, max: 100)
  • tag - Filter webhooks by tag
Response
{
        "webhooks": [
        {
        "id": "abc123def456...",
        "url": "https://webhookbox.com/hook/abc123def456...",
        "description": "Payment Webhook",
        "tags": ["payment", "stripe"],
        "created_at": "2023-06-15T12:30:45Z",
        "request_count": 157
        },
        ...
        ],
        "pagination": {
        "page": 1,
        "limit": 20,
        "total": 42,
        "pages": 3
        }
        }
Create Webhook
POST /webhooks

Create a new webhook endpoint.

Request Body
{
        "description": "Payment Notification Webhook",
        "tags": ["payment", "stripe"],
        "custom_response": {
        "status_code": 200,
        "headers": {
        "Content-Type": "application/json"
        },
        "body": "{\"status\":\"success\"}"
        },
        "forward_url": "https://myapp.example.com/webhooks/payment"
        }
Response
{
        "id": "abc123def456...",
        "url": "https://webhookbox.com/hook/abc123def456...",
        "description": "Payment Notification Webhook",
        "tags": ["payment", "stripe"],
        "created_at": "2023-07-12T08:45:30Z",
        "custom_response": {
        "status_code": 200,
        "headers": {
        "Content-Type": "application/json"
        },
        "body": "{\"status\":\"success\"}"
        },
        "forward_url": "https://myapp.example.com/webhooks/payment",
        "request_count": 0
        }
Get Webhook
GET /webhooks/{id}

Retrieve details for a specific webhook.

Path Parameters
  • id - The webhook ID
Response
{
        "id": "abc123def456...",
        "url": "https://webhookbox.com/hook/abc123def456...",
        "description": "Payment Notification Webhook",
        "tags": ["payment", "stripe"],
        "created_at": "2023-07-12T08:45:30Z",
        "custom_response": {
        "status_code": 200,
        "headers": {
        "Content-Type": "application/json"
        },
        "body": "{\"status\":\"success\"}"
        },
        "forward_url": "https://myapp.example.com/webhooks/payment",
        "request_count": 42,
        "last_request_at": "2023-07-15T14:23:12Z"
        }

Request API

These endpoints allow you to access and manage webhook request data.

List Requests
GET /webhooks/{webhook_id}/requests

Retrieve a list of requests for a specific webhook.

Path Parameters
  • webhook_id - The webhook ID
Query Parameters
  • page - Page number for pagination (default: 1)
  • limit - Number of results per page (default: 20, max: 100)
  • method - Filter by HTTP method (e.g., GET, POST)
  • from - Filter by date range start (ISO 8601 format)
  • to - Filter by date range end (ISO 8601 format)
Response
{
        "requests": [
        {
        "id": "req123abc456...",
        "webhook_id": "abc123def456...",
        "method": "POST",
        "headers": {
        "Content-Type": "application/json",
        "User-Agent": "Stripe/1.0"
        },
        "query_params": {
        "source": "dashboard"
        },
        "body_size": 1256,
        "ip_address": "203.0.113.42",
        "created_at": "2023-07-15T14:23:12Z"
        },
        ...
        ],
        "pagination": {
        "page": 1,
        "limit": 20,
        "total": 157,
        "pages": 8
        }
        }
Get Request
GET /webhooks/{webhook_id}/requests/{request_id}

Retrieve details for a specific webhook request, including full request body.

Path Parameters
  • webhook_id - The webhook ID
  • request_id - The request ID
Response
{
        "id": "req123abc456...",
        "webhook_id": "abc123def456...",
        "method": "POST",
        "headers": {
        "Content-Type": "application/json",
        "User-Agent": "Stripe/1.0",
        "Stripe-Signature": "t=1626349874,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd"
        },
        "query_params": {
        "source": "dashboard"
        },
        "body": "{\"id\":\"evt_1JFzUEKX7w9RzW5v\",\"object\":\"event\",\"api_version\":\"2020-08-27\",\"created\":1626349873,\"data\":{\"object\":{\"id\":\"ch_1JFzUDKX7w9RzW5v\",\"object\":\"charge\",\"amount\":2000,\"currency\":\"usd\"}},\"type\":\"charge.succeeded\"}",
        "ip_address": "203.0.113.42",
        "created_at": "2023-07-15T14:23:12Z",
        "forwarding": {
        "url": "https://myapp.example.com/webhooks/payment",
        "status": "success",
        "status_code": 200,
        "response_time": 235,
        "response_headers": {
        "Content-Type": "application/json"
        },
        "response_body": "{\"received\":true,\"processed\":true}"
        }
        }

User API

These endpoints allow you to manage user account settings.

Get User Profile
GET /user

Retrieve the user profile for the authenticated user.

Response
{
        "id": "usr123abc456...",
        "email": "[email protected]",
        "name": "John Doe",
        "created_at": "2023-01-15T08:30:45Z",
        "subscription": {
        "plan": "pro",
        "status": "active",
        "expires_at": "2024-01-15T08:30:45Z"
        },
        "usage": {
        "webhook_count": 12,
        "request_count": 1574,
        "storage_used": 2.45 // in MB
        }
        }
Update User Profile
PATCH /user

Update the user profile for the authenticated user.

Request Body
{
        "name": "John Smith",
        "notification_preferences": {
        "email_notifications": true,
        "webhook_alerts": true
        }
        }
Response
{
        "id": "usr123abc456...",
        "email": "[email protected]",
        "name": "John Smith",
        "created_at": "2023-01-15T08:30:45Z",
        "notification_preferences": {
        "email_notifications": true,
        "webhook_alerts": true
        },
        "subscription": {
        "plan": "pro",
        "status": "active",
        "expires_at": "2024-01-15T08:30:45Z"
        }
        }

Error Handling

Web Hook Box API uses conventional HTTP response codes to indicate the success or failure of an API request.

Code Description
200 - OK The request was successful.
201 - Created The request has been fulfilled and a new resource has been created.
400 - Bad Request The request was invalid or cannot be otherwise served.
401 - Unauthorized Authentication failed or user doesn't have permissions.
404 - Not Found The requested resource does not exist.
429 - Too Many Requests The user has sent too many requests in a given amount of time.
500, 502, 503, 504 - Server Errors Something went wrong on the server.
Error Response Format

Error responses include a JSON object with detailed information:

{
        "error": {
        "code": "invalid_request",
        "message": "The webhook ID is invalid or does not exist.",
        "status": 404,
        "request_id": "req_7HF9a8sJdK3l2M"
        }
        }
Handling Errors

Always check for error responses in your API clients and handle them appropriately. The request_id field can be useful when contacting support about a specific API issue.

Rate Limiting

Web Hook Box implements rate limiting to protect our infrastructure and ensure fair usage across all users.

Rate Limit Headers

Each API response includes headers that indicate your current rate limit status:

  • X-RateLimit-Limit: The maximum number of requests you're permitted to make per hour.
  • X-RateLimit-Remaining: The number of requests remaining in the current rate limit window.
  • X-RateLimit-Reset: The time at which the current rate limit window resets (UTC epoch seconds).

If you exceed the rate limit, you'll receive a 429 Too Many Requests response with a Retry-After header indicating how long to wait before making another request.

Rate Limit Tiers
Plan Rate Limit
Free 60 requests per hour
Basic 300 requests per hour
Pro 1,000 requests per hour
Enterprise Custom limits