Authentication

Hooksbase has three public auth models, and each one maps to a different job. Use a session for dashboard product flows, a project API key for the Public API, and a webhook ingest or signing secret only for the one webhook that issued it. Secrets are not interchangeable — using the wrong one returns 401.

Every raw secret (project API key, ingest secret, signing secret) is returned exactly once on create or rotate. List and get routes only return non-sensitive metadata and version ledgers. Copy new secrets into your secret manager immediately.

Auth surfaces

  • Name
    Dashboard
    Type
    session auth
    Description

    The Hooksbase dashboard uses your browser session. It is a product UI, not part of the Public API, and is not reachable with a project API key.

  • Name
    Public API
    Type
    project API key
    Description

    The Public API uses Authorization: Bearer swk_.... Use this for webhook configuration, delivery history, replay, usage, and other automation-friendly routes.

  • Name
    Public ingest
    Type
    webhook secret
    Description

    The public ingest surface uses the webhook's whsec_... secret against the webhook-specific ingest URL.

Project API keys

Project API keys have a swk_ prefix and come in two roles:

  • admin can use /v1/project, manage project API keys, and access admin-only project routes such as audit logs and operator notification APIs when the project tier allows them.
  • write can use operational routes such as /v1/webhooks, /v1/deliveries, /v1/dlq, /v1/usage, and webhook schedules, but cannot read or mutate /v1/project or manage project API keys.

Pick the narrowest role that works for the caller. Prefer write for CI, ETL jobs, and agent workloads that only operate on webhooks and deliveries; reserve admin for key management and project settings.

Project API key request

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

API key lifecycle rules are strict:

  • list and get routes never return the raw secret (only the prefix and metadata)
  • create and rotate return the secret exactly once
  • a project cannot revoke its last active admin key — create a replacement first, then revoke the older key

Ingest secrets

Every webhook has its own ingest secret. Use it only when calling that webhook's public ingest URL:

Public ingest request

curl "${INGEST_URL}" \
  -H "Authorization: Bearer whsec_..." \
  -H "content-type: application/json" \
  -d '{"type":"order.created"}'

During a secret-overlap window, Hooksbase accepts both the current ingest secret and the overlapping predecessor until the older version reaches its retiredAt timestamp.

Signing secrets

Signing secrets are outbound-only. Hooksbase uses them to sign deliveries sent to your destination. They are not valid for calling any Hooksbase API route.

Outbound requests include:

  • webhook-id
  • webhook-timestamp
  • webhook-signature

The signature payload is:

{deliveryId}.{unixTimestampSeconds}.<raw body bytes>

The header format is v1,<base64 hmac sha256>. During a signing overlap window Hooksbase can send more than one v1,... signature in the same header.

  • GET /v1/project
  • GET/POST /v1/project/api-keys
  • POST /v1/project/api-keys/{keyId}/revoke
  • POST /v1/project/api-keys/{keyId}/rotate
  • POST /v1/ingest/{publicId}
  • POST /v1/webhooks/{id}/rotate-ingest-secret
  • POST /v1/webhooks/{id}/rotate-signing-secret
  • GET /v1/webhooks/{id}/secret-versions

Common mistakes

  • Expecting a project API key to unlock dashboard views. The dashboard uses session auth and is not reachable via swk_ keys.
  • Using a write key for an admin-only route such as /v1/project.
  • Reusing one webhook's ingest secret with another webhook's ingest URL.
  • Verifying the signature against a reconstructed string instead of the raw body bytes.

Was this page helpful?