Webhooks

In Hooksbase, a webhook is the unit that accepts inbound events and turns them into delivery attempts against one or more destinations. Creating a webhook provisions the public ingest URL, the signing surface, the delivery controls, and the lifecycle state that everything else builds on.

Auth model

Webhook lifecycle

Creating a webhook with POST /v1/webhooks returns:

• the webhook ID (id, e.g. wh_...) — use this for every management API call
• a public ID (publicId, e.g. hook_...) — the unguessable identifier embedded in the ingest and form URLs
• ingestUrl, formIngestUrl, and emailIngestAddress
• the one-time ingestSecret and signingSecret — saved nowhere else, available only on create and on secret rotation

Webhook status transitions through three states:

• active — ingest accepted, deliveries execute
• paused — producers are rejected; configuration remains editable
• archived — no ingest; history and secrets remain inspectable

Lifecycle behavior that matters:

• paused webhooks reject new ingest with 409
• archived webhooks return 404 for public ingest
• archived webhooks still keep delivery history, metrics, backlog, and secret version inspection available
• destroy is only allowed after the webhook has been archived, and it cannot be undone

Delivery controls

Hooksbase ships a small set of delivery controls directly on the webhook:

• deliveryMode: parallel or strict_fifo
• maxInFlight for parallel delivery concurrency
• timeoutMs for upstream request timeout
• retryPolicy for terminal and retry timing behavior
• defaultDelaySeconds for scheduled-by-default ingest
• throttleRatePerSecond for paced outbound traffic

Tier gates matter here:

• Starter+ is required for non-default retry policies and non-empty outbound custom headers
• Pro+ is required for strict_fifo, non-null defaultDelaySeconds, non-null throttleRatePerSecond, and non-webhook destination types

Destinations and routing

Every webhook has one default destination. You can also add named destinations and, on the advanced surface, route to exactly one destination per delivery.

Recommended progression:

• start with one default webhook destination
• add named destinations only when you need controlled cutovers or environment splits
• treat routing as an advanced workflow because delivery rows persist the chosen destination snapshot for retries and replay

The current destination types are:

• webhook
• aws_sqs
• aws_eventbridge
• gcp_pubsub
• object_storage

When you move beyond one default target, use the advanced guides together:

• Providers and templates for provider-aware inbound bootstrap and template-created routing presets
• Routing and destinations for destination types, route-to-one rules, and priority ordering
• Payload transforms for JSON reshaping after route selection
• Schedules for recurring deliveries and default scheduled payloads

Operational actions

Operational actions live on the webhook itself:

• pause and resume
• archive and restore
• destroy
• rotate ingest secret
• rotate signing secret
• inspect secret versions
• run test delivery

Related routes:

• GET/POST /v1/webhooks
• GET/PATCH /v1/webhooks/{id}
• POST /v1/webhooks/{id}/pause
• POST /v1/webhooks/{id}/resume
• POST /v1/webhooks/{id}/archive
• POST /v1/webhooks/{id}/restore
• POST /v1/webhooks/{id}/destroy
• POST /v1/webhooks/{id}/test-delivery
• GET/POST /v1/webhooks/{id}/destinations
• GET/PUT /v1/webhooks/{id}/routing
• GET/PUT /v1/webhooks/{id}/transform
• GET/POST /v1/webhooks/{id}/schedules

Common mistakes

• Treating pause and archive as the same state. They have different ingest behavior and recovery paths.
• Enabling strict_fifo while also expecting future scheduling with x-hooksbase-deliver-at.
• Assuming destroy is reversible.
• Forgetting that advanced destinations and several delivery controls are tier-gated.