API Reference
Complete reference for the Webhook observability API. All endpoints return JSON. Auth-protected routes require a valid JWT cookie or X-API-Key header.
No endpoints match your search.
Authentication
POST
/api/auth/register
Register a new user account with email and password.
Request Body
{
"email": "user@example.com",
"password": "securePassword123"
}
Response 201
{
"id": "usr_abc123",
"email": "user@example.com",
"created_at": "2026-03-12T10:00:00Z"
}
POST
/api/auth/login
Authenticate with email and password. Returns a JWT token set as an HTTP-only cookie.
Request Body
{
"email": "user@example.com",
"password": "securePassword123"
}
Response 200
{
"ok": true,
"token": "eyJhbGciOiJIUzI1NiIs..."
}
The JWT is also set as a secure HTTP-only cookie named token.
POST
/api/auth/forgot-password
Send a password reset link to the provided email address.
Request Body
{
"email": "user@example.com"
}
Response 200
{
"ok": true,
"message": "If that email exists, a reset link has been sent."
}
POST
/api/auth/reset-password
Reset the user password using a token from the reset email.
Request Body
{
"token": "reset_tok_xyz789",
"new_password": "newSecurePassword456"
}
Response 200
{
"ok": true,
"message": "Password has been reset."
}
Projects
GET
/api/projects
Retrieve all projects belonging to the authenticated user.
Response 200
[
{
"id": "proj_abc123",
"name": "My App",
"slug": "my-app-x7k2",
"created_at": "2026-03-01T08:00:00Z"
}
]
POST
/api/projects
Create a new project. A unique ingest slug is generated automatically.
Request Body
{
"name": "My App"
}
Response 201
{
"id": "proj_abc123",
"name": "My App",
"slug": "my-app-x7k2",
"created_at": "2026-03-12T10:00:00Z"
}
DELETE
/api/projects/{id}
Delete a project from the account. This does not guarantee deletion of object-storage copies, backups, or every derived operational record.
| Parameter | Type | Description |
|---|---|---|
| id | string | Project ID (path parameter) |
Response 200
{
"ok": true
}
Events
GET
/api/projects/{id}/events
List webhook events for a project with pagination, status filtering, and date range.
| Parameter | Type | Description |
|---|---|---|
| id | string | Project ID (path parameter) |
| page | int | Page number (default: 1) |
| status | string | Filter by status: success, failed, pending |
| type | string | Filter by event type header |
| search | string | Full-text search in event body |
| since | string | ISO 8601 start date |
| until | string | ISO 8601 end date |
Response 200
{
"events": [
{
"id": "evt_xyz789",
"project_id": "proj_abc123",
"status": "success",
"method": "POST",
"headers": {},
"received_at": "2026-03-12T09:30:00Z"
}
],
"total": 142,
"page": 1,
"per_page": 50
}
GET
/api/events/{eventId}
Retrieve a single event with its full request body, headers, and delivery details.
| Parameter | Type | Description |
|---|---|---|
| eventId | string | Event ID (path parameter) |
Response 200
{
"id": "evt_xyz789",
"project_id": "proj_abc123",
"status": "success",
"method": "POST",
"headers": { "content-type": "application/json" },
"body": "{...}",
"response_status": 200,
"latency_ms": 152,
"received_at": "2026-03-12T09:30:00Z"
}
POST
/api/events/{eventId}/replay
Replay a previously received webhook event to its configured forward destination.
| Parameter | Type | Description |
|---|---|---|
| eventId | string | Event ID to replay (path parameter) |
Response 200
{
"ok": true,
"replay_status": 200,
"latency_ms": 89
}
Ingest (Webhook Receiving)
POST
/p/{token}
The primary webhook ingress endpoint. Configure your provider (Stripe, GitHub, etc.) to send webhooks to this URL.
| Parameter | Type | Description |
|---|---|---|
| token | string | Project ingress token (from project creation) |
Full URL example:
POST https://webhook.sdnbros.app/p/my-app-x7k2
Content-Type: application/json
{
"event": "payment.completed",
"data": { "amount": 2500 }
}
Response 202
{
"ok": true,
"event_id": "evt_xyz789"
}
Forwarding
GET
/api/projects/{id}/destinations
List all delivery destinations configured for a project.
Response 200
{
"destinations": [
{
"id": "dest_def456",
"project_id": "proj_abc123",
"url": "https://myapp.com/webhooks",
"created_at": "2026-03-10T12:00:00Z"
}
]
}
POST
/api/projects/{id}/destinations
Add a new URL where incoming webhooks will be delivered to.
Request Body
{
"url": "https://myapp.com/webhooks",
"name": "Production API"
}
Response 201
{
"id": "dest_def456",
"project_id": "proj_abc123",
"url": "https://myapp.com/webhooks",
"created_at": "2026-03-12T10:00:00Z"
}
DELETE
/api/destinations/{destId}
Remove a delivery destination. Webhooks will no longer be sent to this URL.
| Parameter | Type | Description |
|---|---|---|
| destId | string | Destination ID (path parameter) |
Response 200
{
"ok": true
}
Analytics
GET
/api/analytics/overview
Get aggregated analytics including event volume, status breakdown, and average latency.
Response 200
{
"total_events": 12840,
"success_count": 12100,
"failure_count": 740,
"success_rate": 94.2,
"avg_latency_ms": 187,
"p95_latency_ms": 450
}
GET
/api/analytics/timeline
Get time-series data of event volume for charting.
Response 200
{
"points": [
{ "time": "2026-03-12T00:00:00Z", "count": 342 },
{ "time": "2026-03-12T01:00:00Z", "count": 289 }
]
}
GET
/api/analytics/errors
Get error analytics including failure reasons and status code breakdown.
Response 200
{
"errors": [
{
"status_code": 500,
"count": 45,
"last_seen": "2026-03-12T09:15:00Z"
}
]
}
GET
/api/projects/{id}/failure-patterns
Analyze patterns in webhook failures to identify recurring issues.
Response 200
{
"patterns": [
{
"pattern": "timeout",
"count": 23,
"percentage": 31.1,
"first_seen": "2026-03-10T14:00:00Z",
"last_seen": "2026-03-12T08:45:00Z"
}
]
}
Settings
GET
/api/whoami
Get information about the currently authenticated user.
Response 200
{
"id": "usr_abc123",
"email": "user@example.com",
"email_verified": true,
"created_at": "2026-03-01T08:00:00Z"
}
PATCH
/api/projects/{id}/signing-secret
Update the signing secret used to verify incoming webhook signatures.
Request Body
{
"signing_secret": "whsec_abc123xyz"
}
Response 200
{
"ok": true
}
POST
/api/keys
Generate a new API key for programmatic access. The full key is only shown once.
Request Body
{
"name": "CI/CD Pipeline"
}
Response 201
{
"id": "key_abc123",
"name": "CI/CD Pipeline",
"key": "hk_live_abc123xyz789...",
"created_at": "2026-03-12T10:00:00Z"
}
The full API key is only returned once. Store it securely.
DELETE
/api/keys/{keyId}
Permanently revoke an API key. It will immediately stop working.
| Parameter | Type | Description |
|---|---|---|
| keyId | string | API key ID to revoke (path parameter) |
Response 200
{
"ok": true
}
Billing
GET
/api/billing
Get the current billing plan, usage statistics, and rate limits for the authenticated user.
Response 200
{
"plan": "pro",
"events_used": 8420,
"events_limit": 100000,
"projects_used": 3,
"projects_limit": 25,
"period_start": "2026-03-01T00:00:00Z",
"period_end": "2026-04-01T00:00:00Z"
}
Health
GET
/api/healthz
Basic liveness probe. Returns 200 if the service is running. No authentication required.
Response 200
{
"ok": true
}
GET
/api/status
Detailed service status including database connectivity, ingest server, and dashboard health. No authentication required.
Response 200
{
"status": "healthy",
"components": {
"database": { "status": "up", "latency_ms": 2 },
"ingest": { "status": "up", "port": 8080 },
"dashboard": { "status": "up", "port": 3000 }
},
"version": "1.2.0",
"uptime": "72h15m"
}