API Reference

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

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