--- title: API Reference canonical: https://webhook-box.com/documentation/api-reference last-modified: 2026-08-23 source: Web Hook Box documentation --- # API Reference Complete reference for the Web Hook Box REST API. ##### API Base URL All API requests should be made to: `https://webhook-box.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 ##### On This Page - [Overview](#overview) - [Authentication](#authentication) - [API Endpoints](#endpoints) - [Webhook API](#webhooks) - [Request API](#requests) - [User API](#users) - [Error Handling](#errors) ## 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://webhook-box.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](/documentation/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://webhook-box.com/webhook/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://webhook-box.com/webhook/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://webhook-box.com/webhook/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": "user@example.com", "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": "user@example.com", "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