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
On This Page
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
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 |
Webhook API
These endpoints allow you to create and manage webhook endpoints.
List Webhooks
/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
/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
/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
/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
/webhooks/{webhook_id}/requests/{request_id}
Retrieve details for a specific webhook request, including full request body.
Path Parameters
webhook_id
- The webhook IDrequest_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
/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
/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 |