Ingest

Public ingest is how you turn an external event into a Hooksbase delivery. You send a request to one webhook-specific ingest URL, authenticate with that webhook's ingest secret, and Hooksbase persists the source payload before the delivery coordinator takes over.

Auth model

Public ingest contract

Ingest accepts the raw request body and records it as the source payload for the delivery. Ingest is served on hooks.hooksbase.com (not api.hooksbase.com). JSON is not required unless the webhook has a saved payload transform or a provider verifier that expects JSON.

Body size is capped at 10 MB; larger requests return 413.

curl https://hooks.hooksbase.com/v1/ingest/hook_123 \
  -H "Authorization: Bearer whsec_..." \
  -H "content-type: application/json" \
  -H "Idempotency-Key: order_123" \
  -d '{
    "type": "order.created",
    "orderId": "ord_123"
  }'

Success returns:

• deliveryId
• sequenceNo
• status of queued or scheduled

Duplicate idempotent calls return duplicate: true and the existing delivery reference instead of creating a second delivery.

Scheduling and idempotency

Use the x-hooksbase-deliver-at header to request a future delivery time as a Unix timestamp in milliseconds (the SDK exposes this as the deliverAt option).

Scheduling rules:

• the explicit header overrides the webhook default delay
• per-request future delivery with x-hooksbase-deliver-at and webhook-level default delivery delay require Pro+ support
• recurring cron schedules are managed through /v1/webhooks/{id}/schedules and require Starter+
• strict_fifo webhooks reject future scheduling
• if the effective delivery time is in the past, Hooksbase accepts it immediately

Idempotency matters because it makes retries safe:

• send an Idempotency-Key whenever you might retry
• duplicate ingest does not consume storage or backlog twice
• duplicate repair can restore a missing sequence number when the first request persisted but coordinator handoff was interrupted

Routing, transforms, and quotas

Before a delivery is persisted, Hooksbase evaluates:

• webhook and project lifecycle state
• routing against the original source payload and headers
• payload transforms when configured
• ingest-rate, backlog, and stored-payload quota admission

Important behavior:

• routing always sees the original payload, not the transformed outbound body
• transform-enabled ingest requires JSON input and JSON output
• paused destination routing failures return 400 before persistence
• paused webhook ingest returns 409
• archived or missing webhook ingest returns 404
• disabled project ingest returns 409

Common mistakes

• Forgetting the Authorization: Bearer whsec_... header.
• Publishing JSON-looking data with the wrong content type and then enabling a transform.
• Assuming a changed route rule or transform will affect existing deliveries or replays.
• Scheduling into the future on a webhook configured for strict_fifo.