Webhook.pub API Documentation

Complete guide to integrating with the Webhooks service

Overview Quick Start Endpoints Organization Tagging Errors

Overview

The Webhook.pub API allows you to receive and organize webhook events from external services. Create sites, organize events into folders, and track all incoming webhook data.

Base URL

https://webhook.pub/api

Rate Limits

None - designed for high volume

Authentication

All API requests require authentication using a Bearer token with your site's API key.

Required Header

Authorization string required Bearer token with your site's API key: Bearer your-api-key-here

Authentication Example

curl -H "Authorization: Bearer your-api-key-here" \
     -X POST https://webhook.pub/api/events
Security Note: Keep your API key secure and never expose it in client-side code. Each site has its own unique API key that you can find in your site settings.

Quick Start

Get started with webhook integration in three simple steps:

1

Create a Site

Sign up and create your first site to get a unique slug like my-app-prod

2

Configure Your Webhooks

Point your services to https://webhook.pub/api/events with your API key in the Authorization header

3

Monitor Events

Events will appear automatically in your dashboard, organized and ready to explore

API Endpoints

POST /api/events

Create a new webhook event. This is the main endpoint for receiving webhook data from external services.

Headers

Authorization string required Bearer token with your site's API key
Content-Type string optional The content type of your webhook data (e.g., application/json)

Query Parameters

folder string optional Folder path for organizing the event (e.g., "payments" or "github/issues")
name string optional Custom name for the webhook event (e.g., "Payment Success", "User Signup")
tags string optional Comma-separated tags for categorizing events (e.g., "production,stripe" or "api-error")

Request Body

Send any data in the request body. The entire body content will be stored as the webhook event data, regardless of content type.

Example Requests

JSON Webhook
curl -X POST https://webhook.pub/api/events \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"event": "payment.completed", "amount": 2999}'
With Folder Organization
curl -X POST https://webhook.pub/api/events?folder=stripe/payments \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"event": "payment.completed", "amount": 2999}'
With Custom Name and Folder
curl -X POST "https://webhook.pub/api/events?folder=stripe/payments&name=Payment Success" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"event": "payment.completed", "amount": 2999}'
With Tags
curl -X POST "https://webhook.pub/api/events?tags=production,stripe" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"event": "payment.completed", "amount": 2999}'
Complete Example (Folder, Name, and Tags)
curl -X POST "https://webhook.pub/api/events?folder=stripe/payments&name=Payment Success&tags=production,stripe,payments" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"event": "payment.completed", "amount": 2999, "customer_id": "cus_12345"}'
Text Data
curl -X POST https://webhook.pub/api/events \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: text/plain" \
  -d 'Simple webhook notification'

Response

201 Created 
{
  "status": "received",
  "event_id": "12345",
  "message": "Webhook event created successfully"
}
GET /api/events

List webhook events for your site with pagination.

Headers

Authorization string required Bearer token with your site's API key

Query Parameters

page integer optional Page number (default: 1)
per_page integer optional Events per page (default: 50, max: 100)

Response

200 OK 
{
  "events": [
    {
      "id": 123,
      "name": "Payment Success",
      "created_at": "2024-01-02T10:30:00Z",
      "updated_at": "2024-01-02T10:30:00Z",
      "folder": {
        "id": 456,
        "name": "payments",
        "path": "stripe/payments"
      },
      "tags": ["production", "stripe", "payments"]
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 250,
    "per_page": 50
  }
}
GET /api/events/{id}

Get a specific webhook event including its body content.

Path Parameters

id integer required The webhook event ID

Response

200 OK 
{
  "id": 123,
  "name": "Payment Success",
  "created_at": "2024-01-02T10:30:00Z",
  "updated_at": "2024-01-02T10:30:00Z",
  "body": "{\"event\": \"payment.succeeded\", \"amount\": 1000}",
  "folder": {
    "id": 456,
    "name": "payments",
    "path": "stripe/payments"
  },
  "tags": ["production", "stripe", "payments"]
}
PATCH /api/events/{id}

Update a webhook event's body content or folder assignment.

Request Body

{
  "webhook_event": {
    "body": "updated content",
    "folder_id": 456
  }
}

Response

200 OK

Returns the updated webhook event (same format as GET)

DELETE /api/events/{id}

Delete a webhook event permanently.

Response

200 OK 
{
  "success": true,
  "message": "Webhook event deleted"
}

Organizing Webhooks into Folders

You can automatically organize your webhook events into folders by including a folder query parameter in your webhook URL. This helps keep related events grouped together.

Folder Parameter Examples

Webhook URL Folder Structure Description
/api/events?folder=payments payments/ All events go into the "payments" folder
/api/events?folder=github/issues github/issues/ Events go into "issues" subfolder within "github"
/api/events?folder=service/webhooks/payments service/webhooks/payments/ Deep nesting for complex organization
/api/events (unassigned) Events without folder parameter remain unassigned

Benefits of Using Folders

  • Automatic Organization: No manual sorting required - events are automatically placed in the correct folder
  • Easy Filtering: View events by folder to focus on specific types of webhooks
  • Hierarchical Structure: Create nested folder structures for complex setups using forward slashes
  • Clear Separation: Keep production, staging, and different service events separate
Note: Use forward slashes (/) in the folder parameter to create nested folder structures. For example, folder=prod/payments/stripe creates a three-level hierarchy.

Tagging Webhook Events

You can categorize webhook events using tags by including a tags query parameter in your webhook URL. Tags help organize and filter events across different services and environments.

Tag Parameter Examples

Webhook URL Tags Created Use Case
/api/events?tags=production production Mark events from production environment
/api/events?tags=stripe,payments stripe, payments Tag Stripe payment-related events
/api/events?tags=error,critical,alerts error, critical, alerts Categorize error notifications with multiple tags
/api/events?folder=github&tags=deployment,production deployment, production Combine folder organization with tagging

Benefits of Using Tags

  • Flexible Categorization: Tag events by environment, service, priority, or any custom criteria
  • Cross-Service Organization: Use the same tags across different services for consistent categorization
  • Easy Filtering: View all events with specific tags regardless of their folder or site
  • Multiple Categories: Apply multiple tags to single events for complex organization schemes
  • Auto-Creation: Tags are automatically created when first used - no setup required

Tag Format Options

Tags can be provided in multiple formats:

  • Single tag: tags=production
  • Multiple tags (comma-separated): tags=production,stripe,payments
  • With spaces (URL encoded): tags=api%20error,critical
Note: Tags are case-sensitive and unique per user. Use consistent naming conventions like "production" instead of "Production" or "PRODUCTION" to avoid duplicates.

Error Handling

404 Not Found

Site slug not found or site is inactive

{
  "error": "Site not found",
  "message": "No active site found with slug 'invalid-slug'"
}

413 Payload Too Large

Webhook payload exceeds size limit (usually 10MB)

{
  "error": "Payload too large",
  "message": "Webhook payload must be under 10MB"
}

429 Too Many Requests

Rate limit exceeded (if applicable)

{
  "error": "Rate limit exceeded",
  "message": "Too many requests, please try again later"
}