Raw HTTP Examples

These examples show the HTTP contract behind Hooksbase public routes. Use them when you want cURL-level visibility, need a non-TypeScript language, or are working with browser/raw surfaces such as form ingest. Many of these operations also have first-party SDK and CLI wrappers.

How to read these examples

Examples use swk_... for project API keys. Routes that say admin project key require a project API key with the admin role; a write key returns 403.

Responses are trimmed to show the fields that matter for integration code.

Project API keys

Project API-key lifecycle routes require an admin project API key. Create and rotate responses are the only time the raw key secret is returned.

Create a write key

curl https://api.hooksbase.com/v1/project/api-keys \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent runner",
    "role": "write"
  }'

201 response

{
  "apiKey": "swk_...",
  "key": {
    "id": "key_123",
    "name": "Agent runner",
    "role": "write",
    "keyPrefix": "swk_pk_abc",
    "revokedAt": null
  }
}

Rotate a key

curl https://api.hooksbase.com/v1/project/api-keys/key_123/rotate \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent runner rotated",
    "role": "write"
  }'

Audit logs

Audit logs require an admin project API key and Business+. They are read-only and cursor-paginated.

List audit logs

curl "https://api.hooksbase.com/v1/project/audit-logs?kind=webhook&limit=20" \
  -H "Authorization: Bearer swk_..."

200 response

{
  "items": [
    {
      "id": "audit_123",
      "kind": "webhook",
      "action": "updated",
      "actor": {
        "type": "project_api_key",
        "apiKeyId": "key_123"
      },
      "metadata": {
        "changedFields": ["status"]
      },
      "createdAt": 1766600000000
    }
  ],
  "nextCursor": null
}

Operator alerting

Operator alerting routes require an admin project API key. Creating, patching, resuming, restoring, and rotating alert webhooks require Pro+. The SDK and CLI also wrap this route family; these examples show the underlying HTTP contract.

Create an alert webhook

curl https://api.hooksbase.com/v1/project/operator-webhooks \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "On-call alerts",
    "targetUrl": "https://alerts.example.com/hooksbase",
    "eventTypes": [
      "terminal_failure_spike",
      "destination_health",
      "dlq_accumulation"
    ]
  }'

201 response

{
  "id": "opwh_123",
  "name": "On-call alerts",
  "status": "active",
  "targetUrl": "https://alerts.example.com/hooksbase",
  "eventTypes": [
    "terminal_failure_spike",
    "destination_health",
    "dlq_accumulation"
  ],
  "signingSecret": "sws_..."
}

List open incidents

curl "https://api.hooksbase.com/v1/project/operator-incidents?status=open&limit=20" \
  -H "Authorization: Bearer swk_..."

Metrics and backlog

Metrics and backlog use a window query value. Supported values are 1h, 24h, 7d, and 30d. The default is 24h.

Read webhook metrics

curl "https://api.hooksbase.com/v1/webhooks/wh_123/metrics?window=24h" \
  -H "Authorization: Bearer swk_..."

Read backlog history

curl "https://api.hooksbase.com/v1/webhooks/wh_123/backlog?window=7d" \
  -H "Authorization: Bearer swk_..."

Use GET /v1/usage when you need project usage over explicit from/to timestamps.

Read usage for a time range

curl "https://api.hooksbase.com/v1/usage?from=1766515200000&to=1766601600000" \
  -H "Authorization: Bearer swk_..."

Email allowlists

Listing an email allowlist is project-authenticated. Creating and deleting entries require Starter+.

Add an allowlist entry

curl https://api.hooksbase.com/v1/webhooks/wh_123/email-allowlist \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "*@example.com"
  }'

201 response

{
  "id": "esal_123",
  "webhookId": "wh_123",
  "projectId": "proj_123",
  "pattern": "*@example.com",
  "createdAt": 1766600000000
}

Delete an allowlist entry

curl -X DELETE https://api.hooksbase.com/v1/webhooks/wh_123/email-allowlist/esal_123 \
  -H "Authorization: Bearer swk_..."

Bulk replay and DLQ re-drive

Bulk operations require Starter+ and an Idempotency-Key. They return 202 with a bulk-operation view; poll the returned operation id until job.status is completed or completed_with_errors.

Create a bulk replay job

curl https://api.hooksbase.com/v1/deliveries/bulk-replay \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: replay-failed-orders-2026-04-25" \
  -d '{
    "filters": {
      "webhookId": "wh_123",
      "status": "failed"
    },
    "maxItems": 100
  }'

Create a bulk DLQ re-drive job

curl https://api.hooksbase.com/v1/dlq/bulk-re-drive \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dlq-redrive-orders-2026-04-25" \
  -d '{
    "filters": {
      "webhookId": "wh_123",
      "errorCode": "http_500"
    },
    "maxItems": 50
  }'

Poll a bulk operation

curl https://api.hooksbase.com/v1/bulk-operations/bulk_123 \
  -H "Authorization: Bearer swk_..."

Event drains

Event drains are project-authenticated routes despite the /v1/app prefix. Create, patch, and resume require Pro+; Pro allows one drain, Business allows three, and Enterprise is unbounded. The SDK and CLI also wrap this route family.

Create a webhook drain

curl https://api.hooksbase.com/v1/app/event-drains \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Delivery stream",
    "sinkType": "webhook",
    "sinkConfig": {
      "url": "https://observability.example.com/hooksbase",
      "signingSecret": "drain-secret"
    },
    "eventTypes": [
      "delivery.created",
      "attempt.completed",
      "delivery.failed"
    ],
    "filterWebhookIds": ["wh_123"]
  }'

201 response

{
  "id": "drain_123",
  "name": "Delivery stream",
  "status": "active",
  "sinkType": "webhook",
  "eventTypes": [
    "delivery.created",
    "attempt.completed",
    "delivery.failed"
  ],
  "filterWebhookIds": ["wh_123"],
  "consecutiveFailures": 0
}

Pause and resume

curl -X POST https://api.hooksbase.com/v1/app/event-drains/drain_123/pause \
  -H "Authorization: Bearer swk_..."

curl -X POST https://api.hooksbase.com/v1/app/event-drains/drain_123/resume \
  -H "Authorization: Bearer swk_..."