Webhook Inbox API Reference

Webhook inboxes give you a stable, publicly reachable URL that captures every incoming HTTP request — method, headers, body, and query string — without you running any server. You can inspect captured requests through the API or subscribe to a WebSocket channel to see them arrive in real time. Each webhook inbox is reachable at:

https://<team_referenceId>-<project_slug>.swisstools.dev/api/webhook/<referenceId>

For example, if your team referenceId is aB3cD4eF and your project slug is payments-api, a webhook with referenceId wbhkXyZ123abcABC is reachable at:

https://aB3cD4eF-payments-api.swisstools.dev/api/webhook/wbhkXyZ123abcABC

Captured requests are stored for 12 hours, with a maximum of 50 per inbox. The inbox URL is public — no auth needed for external services to send requests to it. All management endpoints require session authentication. See Authentication for details.

List Webhooks

GET /api/projects/:projectId/webhooks Returns all webhook inboxes for the specified project. Path Parameters

string

required

The UUID of the project.

Request

curl https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/webhooks \
  -b cookies.txt

Response

[
  {
    "id": "018e7d5e-4f6a-0b1c-d2e3-5f6a7b8c9d0e",
    "referenceId": "wbhkXyZ123abcABC",
    "projectId": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
    "name": "Stripe Events",
    "description": "Capture Stripe payment events",
    "expiresAt": null,
    "createdAt": "2024-02-15T12:00:00.000Z",
    "updatedAt": "2024-02-15T12:00:00.000Z"
  }
]

Create Webhook

POST /api/projects/:projectId/webhooks Creates a new webhook inbox. Path Parameters

string

required

The UUID of the project.

Request Body

string

required

A human-readable name for the webhook inbox.

string

An optional description of what this inbox captures.

Request

curl -X POST https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/webhooks \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe Events",
    "description": "Capture Stripe payment events"
  }'

Response — 201 Created

{
  "id": "018e7d5e-4f6a-0b1c-d2e3-5f6a7b8c9d0e",
  "referenceId": "wbhkXyZ123abcABC",
  "projectId": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
  "name": "Stripe Events",
  "description": "Capture Stripe payment events",
  "expiresAt": null,
  "createdAt": "2024-02-15T12:00:00.000Z",
  "updatedAt": "2024-02-15T12:00:00.000Z"
}

Get Webhook

GET /api/projects/:projectId/webhooks/:webhookId Returns a single webhook inbox by its ID. Path Parameters

string

required

The UUID of the project.

string

required

The UUID of the webhook inbox.

Request

curl https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/webhooks/018e7d5e-4f6a-0b1c-d2e3-5f6a7b8c9d0e \
  -b cookies.txt

Response

{
  "id": "018e7d5e-4f6a-0b1c-d2e3-5f6a7b8c9d0e",
  "referenceId": "wbhkXyZ123abcABC",
  "projectId": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
  "name": "Stripe Events",
  "description": "Capture Stripe payment events",
  "expiresAt": null,
  "createdAt": "2024-02-15T12:00:00.000Z",
  "updatedAt": "2024-02-15T12:00:00.000Z"
}

Update Webhook

PUT /api/projects/:projectId/webhooks/:webhookId Updates the name or description of a webhook inbox. Path Parameters

string

required

The UUID of the project.

string

required

The UUID of the webhook inbox to update.

Request Body

string

Updated display name.

string

Updated description.

Request

curl -X PUT https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/webhooks/018e7d5e-4f6a-0b1c-d2e3-5f6a7b8c9d0e \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"name": "Stripe Payment Events", "description": "Only payment.success and payment.failed events."}'

Response

{
  "id": "018e7d5e-4f6a-0b1c-d2e3-5f6a7b8c9d0e",
  "referenceId": "wbhkXyZ123abcABC",
  "projectId": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
  "name": "Stripe Payment Events",
  "description": "Only payment.success and payment.failed events.",
  "expiresAt": null,
  "createdAt": "2024-02-15T12:00:00.000Z",
  "updatedAt": "2024-03-01T09:45:00.000Z"
}

Delete Webhook

DELETE /api/projects/:projectId/webhooks/:webhookId Permanently deletes the webhook inbox and all captured requests stored for it. Path Parameters

string

required

The UUID of the project.

string

required

The UUID of the webhook inbox to delete.

Request

curl -X DELETE https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/webhooks/018e7d5e-4f6a-0b1c-d2e3-5f6a7b8c9d0e \
  -b cookies.txt

Response

{"success": true}

Get Captured Requests

GET /api/projects/:projectId/webhooks/:webhookId/requests Returns the captured HTTP requests received by this webhook inbox, most recent first. Requests are stored for 12 hours with a maximum of 50 entries. Path Parameters

string

required

The UUID of the project.

string

required

The UUID of the webhook inbox.

Request

curl https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/webhooks/018e7d5e-4f6a-0b1c-d2e3-5f6a7b8c9d0e/requests \
  -b cookies.txt

Response

[
  {
    "id": "req_a1b2c3d4e5f6",
    "webhookId": "018e7d5e-4f6a-0b1c-d2e3-5f6a7b8c9d0e",
    "method": "POST",
    "headers": {
      "content-type": "application/json",
      "x-stripe-signature": "t=1706745600,v1=abc123..."
    },
    "body": "{\"event\": \"payment.success\", \"amount\": 4900}",
    "query": {},
    "receivedAt": "2024-02-15T13:00:00.000Z"
  }
]

Real-Time WebSocket Stream

Connect to the WebSocket endpoint to receive captured requests the moment they arrive, without polling. WebSocket URL:

wss://swisstools.dev/ws/webhook/:webhookId

Replace :webhookId with the UUID of the inbox. Connecting:

const ws = new WebSocket(
  'wss://swisstools.dev/ws/webhook/018e7d5e-4f6a-0b1c-d2e3-5f6a7b8c9d0e'
);

ws.addEventListener('message', (event) => {
  const request = JSON.parse(event.data);
  console.log('Received:', request.method, request.body);
});

Each WebSocket message is a JSON string with the same shape as a captured request object (see above). Messages are broadcast to all connected clients subscribed to the same webhook channel.

Webhook Object

string

UUID that uniquely identifies the webhook inbox.

string

A 16-character alphanumeric identifier used in the public inbox URL path.

string

UUID of the project that owns this inbox.

string

Display name of the webhook inbox.

string

Optional description of what this inbox captures.

string

ISO 8601 timestamp at which the inbox will expire, or null if it has no expiry.

string

ISO 8601 timestamp of creation.

string

ISO 8601 timestamp of the last update.

Captured Request Object

string

Unique identifier for the captured request.

string

UUID of the webhook inbox that captured this request.

string

HTTP method of the incoming request (e.g., POST, GET).

object

Key-value map of all HTTP headers sent with the incoming request.

string

The raw request body as a string.

object

Key-value map of URL query parameters from the incoming request.

string

ISO 8601 timestamp of when the request was captured.

Overview

Endpoints

Webhook Inbox API Reference

List Webhooks

Create Webhook

Get Webhook

Update Webhook

Delete Webhook

Get Captured Requests

Real-Time WebSocket Stream

Webhook Object

Captured Request Object

​List Webhooks

​Create Webhook

​Get Webhook

​Update Webhook

​Delete Webhook

​Get Captured Requests

​Real-Time WebSocket Stream

​Webhook Object

​Captured Request Object

List Webhooks

Create Webhook

Get Webhook

Update Webhook

Delete Webhook

Get Captured Requests

Real-Time WebSocket Stream

Webhook Object

Captured Request Object