API Reference

Last updated: April 2026

The WebhookWhisper REST API lets you manage endpoints, retrieve events, configure forwarding rules, and send test webhooks programmatically. All responses are JSON. Base URL: https://webhookwhisper.com

Base URL

webhookwhisper.com

Format

JSON (application/json)

Auth

Bearer token or API key

Related guides

Beyond the API reference below, these companion guides cover signature verification and embedding the live inspector in your own pages.

HMAC signature verification

Verify the webhooks WebhookWhisper sends to your server. Copy-paste recipes for Node.js, Python, Go, Ruby, PHP, and Bash.

Embed the live inspector

Drop the WebhookWhisper inspector into your tutorial, docs site, or blog post with a one-line iframe snippet.

Authentication

Most endpoints require authentication. Pass your token in the Authorization header:

Authorization: Bearer sess_abc123...

# Or with an API key (Pro plan only):
Authorization: Bearer wf_live_abc123...

Get a session token from POST /api/auth/login. Get API keys (Pro only) from your dashboard settings.

Authentication

POST

/api/auth/register

Create a new user account. Returns a session token.

no auth

Request Body (JSON)

name—string — display name (2–100 chars)

email—string — valid email address

password—string — min 8 characters

Response

{
  "data": {
    "user": { "id": "uuid", "name": "Jane", "email": "[email protected]", "plan": "free" },
    "token": "sess_abc123...",
    "expiresAt": "2026-05-09T00:00:00.000Z"
  }
}

POST

/api/auth/login

no auth

Request Body (JSON)

email—string

password—string

Response

{
  "data": {
    "user": { "id": "uuid", "name": "Jane", "email": "[email protected]", "plan": "free" },
    "token": "sess_abc123...",
    "expiresAt": "2026-05-09T00:00:00.000Z"
  }
}

POST

/api/auth/logout

Invalidate the current session token.

Bearer token

Response

{ "data": { "message": "Logged out successfully" } }

GET

/api/auth/me

Get the currently authenticated user.

Bearer token

Response

{
  "data": {
    "user": { "id": "uuid", "name": "Jane", "email": "[email protected]", "plan": "free", "role": "user" }
  }
}

Receiving Webhooks

ALL

/hook/:slug

Your webhook endpoint URL. Accepts any HTTP method (GET, POST, PUT, PATCH, DELETE). Every incoming request is captured, stored, and forwarded per your rules. Returns immediately with a 200 response.

no auth

Response

{ "received": true }

Endpoints

GET

/api/endpoints

List all your webhook endpoints with event counts and last activity.

Bearer token

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "My Stripe Endpoint",
      "slug": "abc123xyz",
      "description": "Stripe payments",
      "isActive": true,
      "webhookUrl": "https://webhookwhisper.com/hook/abc123xyz",
      "eventCount": 42,
      "ruleCount": 2,
      "lastEventAt": "2026-04-09T10:00:00.000Z",
      "createdAt": "2026-04-01T00:00:00.000Z"
    }
  ]
}

POST

/api/endpoints

Create a new webhook endpoint. Returns the endpoint with its unique webhook URL.

Bearer token

Request Body (JSON)

name—string — required (1–100 chars)

description—string — optional (max 500 chars)

secretKey—string — optional, for signature verification

Response

{
  "data": {
    "id": "uuid",
    "name": "My Stripe Endpoint",
    "slug": "abc123xyz",
    "webhookUrl": "https://webhookwhisper.com/hook/abc123xyz",
    "isActive": true,
    "createdAt": "2026-04-09T00:00:00.000Z"
  }
}

GET

/api/endpoints/:id

Get a single endpoint with its forwarding rules and last 20 events.

Bearer token

Response

{
  "data": {
    "endpoint": { "id": "uuid", "name": "...", "webhookUrl": "...", "isActive": true },
    "rules": [ { "id": "uuid", "targetUrl": "https://myapp.com/hooks", "isActive": true } ],
    "recentEvents": [ { "id": "uuid", "method": "POST", "receivedAt": "..." } ]
  }
}

PUT

/api/endpoints/:id

Update endpoint name, description, active status, or custom response settings.

Bearer token

Request Body (JSON)

name—string — optional

description—string — optional

isActive—boolean — optional

customResponseStatus—number — optional, 200–599 (Pro only)

customResponseBody—string — optional JSON string (Pro only)

customResponseHeaders—string — optional JSON string (Pro only)

Response

{ "data": { "id": "uuid", "name": "Updated Name", "isActive": false } }

DELETE

/api/endpoints/:id

Delete an endpoint and all its events and forwarding rules.

Bearer token

Response

{ "data": { "message": "Endpoint deleted successfully" } }

Events

GET

/api/endpoints/:endpointId/events

List events for an endpoint, paginated. Supports filtering by HTTP method and body search.

Bearer token

Query Parameters

page—number — default 1

limit—number — default 50, max 100

method—string — filter by HTTP method (GET, POST, etc.)

search—string — search within request body

Response

{
  "data": [
    {
      "id": "uuid",
      "method": "POST",
      "headers": { "content-type": "application/json", "x-stripe-signature": "t=..." },
      "query": {},
      "body": "{"type":"payment_intent.succeeded","amount":2999}",
      "bodyJson": { "type": "payment_intent.succeeded", "amount": 2999 },
      "sourceIp": "54.187.0.1",
      "size": 1024,
      "receivedAt": "2026-04-09T10:00:00.000Z",
      "deliveryCount": 2,
      "successCount": 2
    }
  ],
  "meta": { "page": 1, "limit": 50, "total": 142, "totalPages": 3 }
}

GET

/api/endpoints/:endpointId/events/:eventId

Get a single event with full headers, body, and all delivery attempt details.

Bearer token

Response

{
  "data": {
    "event": {
      "id": "uuid",
      "method": "POST",
      "headers": { "content-type": "application/json" },
      "body": "{"type":"checkout.session.completed"}",
      "bodyJson": { "type": "checkout.session.completed" },
      "receivedAt": "2026-04-09T10:00:00.000Z"
    },
    "deliveries": [
      {
        "id": "uuid",
        "targetUrl": "https://myapp.com/webhooks",
        "status": "success",
        "statusCode": 200,
        "durationMs": 145,
        "attempt": 1,
        "deliveredAt": "2026-04-09T10:00:01.000Z"
      }
    ]
  }
}

POST

/api/endpoints/:endpointId/events/:eventId/replay

Replay an event to all active forwarding rules. Re-enqueues delivery with retry logic.

PROBearer token

Response

{
  "data": {
    "message": "Event replayed to 2 rule(s)",
    "rulesCount": 2,
    "jobIds": ["job_abc", "job_xyz"]
  }
}

Forwarding Rules

GET

/api/endpoints/:endpointId/rules

List all forwarding rules for an endpoint.

Bearer token

Response

{
  "data": [
    {
      "id": "uuid",
      "endpointId": "uuid",
      "targetUrl": "https://myapp.com/webhooks",
      "httpMethod": "SAME",
      "retryCount": 3,
      "timeoutMs": 10000,
      "isActive": true,
      "customHeaders": "{}",
      "createdAt": "2026-04-01T00:00:00.000Z"
    }
  ]
}

POST

/api/endpoints/:endpointId/rules

Create a forwarding rule. Webhooks received at the endpoint will be forwarded to targetUrl.

Bearer token

Request Body (JSON)

targetUrl—string — required, valid URL (e.g. https://myapp.com/hooks or http://localhost:3000/hooks)

retryCount—number — 0–10. Default: 3

timeoutMs—number — 1000–30000ms. Default: 10000

customHeaders—string — JSON object of extra headers to add. Default: {}

isActive—boolean — Default: true

Response

{
  "data": {
    "id": "uuid",
    "targetUrl": "https://myapp.com/webhooks",
    "httpMethod": "SAME",
    "retryCount": 3,
    "timeoutMs": 10000,
    "isActive": true,
    "createdAt": "2026-04-09T00:00:00.000Z"
  }
}

PUT

/api/endpoints/:endpointId/rules/:ruleId

Update a forwarding rule.

Bearer token

Request Body (JSON)

targetUrl—string — optional

httpMethod—string — optional

retryCount—number — optional

timeoutMs—number — optional

customHeaders—string — optional JSON

isActive—boolean — optional

Response

{ "data": { "id": "uuid", "targetUrl": "https://newurl.com/hooks", "isActive": false } }

DELETE

/api/endpoints/:endpointId/rules/:ruleId

Delete a forwarding rule.

Bearer token

Response

{ "data": { "message": "Rule deleted successfully" } }

Test Sender

GET

/api/test/samples

Get all 35+ available sample payloads (Stripe, GitHub, Shopify, Razorpay, etc.).

no auth

Response

{
  "data": {
    "samples": [
      {
        "id": "uuid",
        "provider": "stripe",
        "eventName": "payment_intent.succeeded",
        "category": "stripe",
        "description": "Payment Intent Succeeded",
        "method": "POST",
        "headers": { "content-type": "application/json", "stripe-signature": "..." },
        "payload": { "type": "payment_intent.succeeded", "data": { "object": { "amount": 2000 } } }
      }
    ]
  }
}

POST

/api/test/send

Send a custom HTTP request to any URL. Returns the response status, headers, body, and latency.

Bearer token

Request Body (JSON)

targetUrl—string — required, URL to send to

method—string — GET | POST | PUT | DELETE | PATCH. Default: POST

headers—object — optional key/value headers

body—string — optional request body

Response

{
  "data": {
    "success": true,
    "statusCode": 200,
    "responseHeaders": { "content-type": "application/json" },
    "responseBody": "{"ok":true}",
    "durationMs": 145
  }
}

POST

/api/test/send-sample

Send a pre-built sample payload from a specific provider to a target URL.

Bearer token

Request Body (JSON)

sampleId—string — ID from GET /api/test/samples

targetUrl—string — URL to send the sample to

Response

{
  "data": {
    "success": true,
    "statusCode": 200,
    "durationMs": 120,
    "sampleUsed": { "provider": "stripe", "eventType": "payment_intent.succeeded", "name": "Payment Intent Succeeded" }
  }
}

API Keys

GET

/api/keys

List your API keys (key prefix and metadata only — full keys are never shown again).

PROBearer token

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "Production Key",
      "keyPrefix": "wf_live_abc",
      "lastUsedAt": "2026-04-09T10:00:00.000Z",
      "createdAt": "2026-04-01T00:00:00.000Z"
    }
  ]
}

POST

/api/keys

Create an API key. The full key is shown only once — save it immediately.

PROBearer token

Request Body (JSON)

name—string — label for this key (1–100 chars)

Response

{
  "data": {
    "id": "uuid",
    "name": "Production Key",
    "keyPrefix": "wf_live_abc",
    "key": "wf_live_abc123xyz...",
    "warning": "Save this key now. You will not be able to see it again.",
    "createdAt": "2026-04-09T00:00:00.000Z"
  }
}

DELETE

/api/keys/:id

Revoke an API key. This immediately invalidates the key.

PROBearer token

Response

{ "data": { "message": "API key revoked successfully" } }

Stats

GET

/api/stats

Get your account stats: endpoint count, event totals, delivery success rate, avg latency. Pro accounts also get hourly chart data.

Bearer token

Response

{
  "data": {
    "endpoints": { "total": 3, "active": 3 },
    "events": { "total": 1420, "today": 87, "lastHour": 12 },
    "deliveries": { "success": 85, "failed": 2, "pending": 0 },
    "rules": { "total": 5, "active": 5 },
    "successRate": 97.7,
    "avgLatencyMs": 143
  }
}

Error Responses

All errors return JSON with an error field:

{ "error": "Endpoint not found" }

// Validation errors include details:
{
  "error": "Validation failed",
  "details": [{ "path": ["name"], "message": "String must contain at least 1 character(s)" }]
}

// Plan limit errors include upgrade info:
{
  "error": "API keys are a Pro feature",
  "upgradeRequired": true
}

Status	Meaning
`200`	OK — request succeeded
`201`	Created — resource created successfully
`400`	Bad Request — validation failed or malformed JSON
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — feature requires a higher plan, or you don't own this resource
`404`	Not Found — endpoint, event, or rule doesn't exist
`410`	Gone — guest endpoint has expired
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error — something went wrong on our end

Code Examples

Create an endpoint and get its URL

# 1. Login to get a token
curl -X POST https://webhookwhisper.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"yourpassword"}'

# Response: { "data": { "token": "sess_abc...", "user": {...} } }

# 2. Create an endpoint
curl -X POST https://webhookwhisper.com/api/endpoints \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sess_abc..." \
  -d '{"name":"My Stripe Endpoint","description":"Production payments"}'

# Response includes webhookUrl: "https://webhookwhisper.com/hook/abc123xyz"

# 3. Add a forwarding rule to your local server
curl -X POST https://webhookwhisper.com/api/endpoints/{endpointId}/rules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sess_abc..." \
  -d '{"targetUrl":"http://localhost:3000/webhooks","retryCount":3}'

List recent events

curl https://webhookwhisper.com/api/endpoints/{endpointId}/events?limit=10 \
  -H "Authorization: Bearer sess_abc..."

Send a Stripe test payload

# 1. Get sample IDs
curl https://webhookwhisper.com/api/test/samples

# 2. Send the sample to your endpoint
curl -X POST https://webhookwhisper.com/api/test/send-sample \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sess_abc..." \
  -d '{
    "sampleId": "uuid-of-stripe-sample",
    "targetUrl": "https://webhookwhisper.com/hook/abc123xyz"
  }'

Rate Limits

Endpoint	Limit
`POST /api/test/send`	Daily limit per user (plan-dependent)
`POST /api/test/send-sample`	Daily limit per user (plan-dependent)
`POST /hook/:slug (receiving)`	No limit on receiving webhooks
`All other API endpoints`	Standard rate limits apply