Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.swisstools.dev/llms.txt

Use this file to discover all available pages before exploring further.

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
​
projectId
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
​
projectId
string
required
The UUID of the project.
Request Body
​
name
string
required
A human-readable name for the webhook inbox.
​
description
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
​
projectId
string
required
The UUID of the project.
​
webhookId
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
​
projectId
string
required
The UUID of the project.
​
webhookId
string
required
The UUID of the webhook inbox to update.
Request Body
​
name
string
Updated display name.
​
description
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
​
projectId
string
required
The UUID of the project.
​
webhookId
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
​
projectId
string
required
The UUID of the project.
​
webhookId
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

​
id
string
UUID that uniquely identifies the webhook inbox.
​
referenceId
string
A 16-character alphanumeric identifier used in the public inbox URL path.
​
projectId
string
UUID of the project that owns this inbox.
​
name
string
Display name of the webhook inbox.
​
description
string
Optional description of what this inbox captures.
​
expiresAt
string
ISO 8601 timestamp at which the inbox will expire, or null if it has no expiry.
​
createdAt
string
ISO 8601 timestamp of creation.
​
updatedAt
string
ISO 8601 timestamp of the last update.

​
Captured Request Object

​
id
string
Unique identifier for the captured request.
​
webhookId
string
UUID of the webhook inbox that captured this request.
​
method
string
HTTP method of the incoming request (e.g., POST, GET).
​
headers
object
Key-value map of all HTTP headers sent with the incoming request.
​
body
string
The raw request body as a string.
​
query
object
Key-value map of URL query parameters from the incoming request.
​
receivedAt
string
ISO 8601 timestamp of when the request was captured.