Raw HTTP Examples

Some public route families are intentionally raw HTTP today. Use these examples when the TypeScript SDK or CLI does not wrap the operation your integration or agent needs yet.

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 routes require an admin project API key. Creating, patching, resuming, restoring, and rotating alert webhooks require Pro+. The route family is raw HTTP; the SDK and CLI do not wrap it yet.

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 raw HTTP routes. Create, patch, and resume require Pro+; Pro allows one drain, Business allows three, and Enterprise is unbounded.

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_..."