Launch special — let's split the check with SPLITCHECK for 50% off
Share feedback →

basics

API Reference

Complete API reference for creating endpoints, listing requests, replaying webhooks, and more.

Base URL

https://hooksense.com/api

Plan Requirements

Most API endpoints are available on every plan, but a handful require a paid plan. The shorthand "Hook+" below means the feature is available on Hook, Sense, and Enterprise — not just Hook. Each tier inherits everything from the tier below it.

CapabilityCatch (Free)Hook ($19)Sense ($49)Enterprise
Endpoint creation, capture, replay, basic API✓✓✓✓
API tokens (hsk_...)—✓✓✓
HMAC verification, custom URL/response, export, email alerts—✓✓✓
Health dashboard, Slack/Discord channels——✓✓
Custom domains, auto-retry, auto-diagnosis, IP allowlisting, request transform on replay——✓✓
Audit log, SSO———✓

If you hit a paywalled endpoint on the wrong plan you'll get a 402 or 403 response with {"error": "...", "upgrade": true} — clients should surface an upgrade CTA on that signal. Full per-plan limits at Limits & Quotas.

OpenAPI Specification

The full machine-readable spec is published at both endpoints:

Import into Postman: File → Import → paste https://hooksense.com/openapi.json. Postman generates a full collection automatically.

Import into Insomnia / Bruno / Hoppscotch: all support the same OpenAPI URL.

Generate a client SDK: point any OpenAPI generator (openapi-typescript, openapi-generator-cli, etc.) at the JSON URL.

Authentication

The API authenticates via the same session cookie the web UI uses. Two ways to authenticate:

  • Session cookie — sign in via the web UI, then send Cookie: hs_session=... on each request. Easiest for scripts on a developer machine.
  • API token (Hook+) — generate from Account → API tokens. Send as Authorization: Bearer hsk_.... Recommended for CI/automation.

All responses are JSON. Errors return {"error": "human-readable message"} with an appropriate HTTP status (400/401/403/404/422/429/500).

Rate Limits

  • Authenticated API: 600 requests/minute per user
  • Webhook capture: 60 requests/minute per IP per endpoint (separate from API quota)
  • Exceeded responses include Retry-After header in seconds

Endpoint Resource

Create Endpoint

POST /api/endpoints

curl -X POST https://hooksense.com/api/endpoints \
  -H "Authorization: Bearer hsk_..." \
  -H "Content-Type: application/json" \
  -d '{"slug":"my-stripe-prod"}'

Body fields (all optional): slug (Hook+ for custom slugs), teamId (to create within a team).

Returns 201 with the endpoint object on success, 409 if the slug is taken, 402 if you've hit your plan's endpoint limit.

List Endpoints

GET /api/endpoints

Returns all endpoints owned by the authenticated user (or members of teams they belong to). Pagination via ?page and ?limit (default 50, max 200).

Get Endpoint

GET /api/endpoints/:slug

Returns endpoint details including settings, custom response config, and webhook secret status (the secret itself is never returned — only hasSecret: true|false).

Update Endpoint

PATCH /api/endpoints/:slug

Update endpoint settings. Supported fields:

  • slug — Custom endpoint slug (Hook+, see Custom URLs)
  • customResponseStatus — HTTP status code 100–599 (Hook+)
  • customResponseBody — Response body string up to 10 KB (Hook+)
  • customResponseHeaders — Object of header key→value pairs (Hook+)
  • webhookSecret — HMAC signing secret; pass empty string to clear (Hook+)
  • signatureProvider — One of: auto, stripe, github, shopify, twilio, custom (Hook+)
  • inactivityThreshold — Minutes before "no incoming requests" alert: 30, 60, 120, 360, 720, 1440 (Hook+)
  • customDomain — Custom hostname (Sense, see Custom Domains)

Delete Endpoint

DELETE /api/endpoints/:slug

Permanently deletes the endpoint and all captured requests. Returns 204 on success. Cannot be undone.

Request Resource

List Requests

GET /api/endpoints/:slug/requests

Query params:

  • search — Substring match across body, headers, source IP
  • method — Filter to single method (GET, POST, etc.)
  • verified — true, false, or omit for all
  • since / until — ISO 8601 timestamps
  • limit — Page size (default 100, max 500)
  • cursor — Pagination cursor from previous response

Get Request

GET /api/endpoints/:slug/requests/:requestId

Returns full request including raw body. The capture-time payload cap depends on your plan — 1 MB on Catch (Free), 10 MB on Hook / Sense, 25 MB on Enterprise. Requests over the cap are rejected at capture time with a 413.

Replay Request

POST /api/endpoints/:slug/replay/:requestId

curl -X POST https://hooksense.com/api/endpoints/my-slug/replay/req_01H... \
  -H "Authorization: Bearer hsk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://staging.example.com/webhooks",
    "method": "POST",
    "headers": { "X-Replay-Source": "hooksense" },
    "body": "{...}",
    "repeat": 1,
    "delayMs": 0
  }'

All body fields are optional — defaults replay the captured request unmodified to the original target. SSRF protection rejects internal IPs.

Export Requests

GET /api/endpoints/:slug/export?format=json|csv

Streams the response. Optional since, until, verified filters. Hook+ required.

Monitoring & Alerts

Health Metrics

GET /api/endpoints/:slug/metrics?period=24h|7d|30d

Returns { status, summary, timeline }. summary contains total, success, fail, failRate, avgLatencyMs. timeline is an array of { bucketStart, total, fail, avgLatencyMs } with bucket size matching the period (hourly for 24h/7d, daily for 30d). Hook+ required.

Health Summary (lightweight)

GET /api/endpoints/:slug/metrics/summary

Returns { status, total24h, failRate24h } in <100 ms — suitable for status-page integrations. Hook+ required.

List Alerts

GET /api/endpoints/:slug/alerts

Returns active and recent alert states. Hook+ required.

Retry History

GET /api/endpoints/:slug/retries

Lists retry jobs with status, attempt count, response, and next retry time. Sense required.

Create Retry Job

POST /api/endpoints/:slug/retries

Body: { "requestId": "req_..." }. Manually triggers a retry for a failed request. Sense required.

Diagnose Request

POST /api/requests/diagnose

Body: { "requestId": "req_..." }. Returns category, severity, and actionable suggestion. Sense required.

Notification Channels

List Channels

GET /api/notifications/channels

Create Channel

POST /api/notifications/channels

Body: { "type": "email"|"slack"|"discord", "target": "...", "scope": "all"|"endpoint", "endpointId": "..." }. For Slack/Discord, target is the incoming webhook URL.

Update / Delete / Test

  • PATCH /api/notifications/channels/:id — toggle enabled, change scope
  • DELETE /api/notifications/channels/:id
  • POST /api/notifications/channels/:id/test — sends a test notification

Custom Domains

Add / Verify Domain

POST /api/endpoints/:slug/domain — body { "domain": "webhooks.yourapp.com" }. Triggers CNAME verification and TLS provisioning.

Domain Status

GET /api/endpoints/:slug/domain — returns { status: "pending"|"active"|"failed", reason: "..." }.

Remove Domain

DELETE /api/endpoints/:slug/domain

Teams

List / Create / Get / Delete

  • GET /api/teams — teams the user belongs to
  • POST /api/teams — body { "name": "..." }
  • GET /api/teams/:id — team details + members
  • PATCH /api/teams/:id — rename, transfer ownership
  • DELETE /api/teams/:id — owner only

Members

  • POST /api/teams/:id/invites — body { "email": "...", "role": "admin|member|viewer" }
  • POST /api/teams/:id/invites/accept — body { "token": "..." }
  • PATCH /api/teams/:id/members/:userId — change role
  • DELETE /api/teams/:id/members/:userId — remove member

Sharing

Create Share Link

POST /api/endpoints/:slug/share — body { "scope": "live"|"history"|"request", "requestId": "...", "expiresIn": 3600 }. Returns { "url": "https://hooksense.com/share/..." }.

Revoke Share Link

DELETE /api/endpoints/:slug/share/:token

Billing

  • POST /api/billing/checkout — body { "plan": "hook"|"sense", "yearly": true|false } — returns { "url": "..." } for Polar checkout
  • POST /api/billing/portal — returns { "url": "..." } for Polar customer portal

Auth

  • GET /api/auth/me — current user (or 401)
  • POST /api/auth/login — email + password
  • POST /api/auth/signup — email + password
  • POST /api/auth/logout
  • GET /api/auth/github/login — initiates GitHub OAuth flow

Webhooks (incoming)

Public capture endpoints — these receive webhooks from your providers, they're not part of the management API. No auth, rate-limited per IP.

  • Default: POST/GET/PUT/DELETE/PATCH https://hooksense.com/w/:slug
  • Custom domain: any HTTP method on https://your.custom.domain/ (or /:path for multi-path routing)
PreviousCLINext Webhook Capture