# Onboarding

Hooksbase includes a guided onboarding layer so a new project does not have to discover every webhook setting from scratch. The dashboard tracks onboarding state, presents a fixed blueprint catalog, and can run a synthetic validation against the webhook you are setting up.

## What onboarding does

Onboarding stores a small project-level state object that tracks:

- whether onboarding is still active or already completed
- which path the user selected
- the current tracked webhook ID
- the last validation timestamp

That state lives in project metadata and is refreshed whenever the dashboard loads the onboarding snapshot.

## Auth model

- **Dashboard** `session auth`: Onboarding and the workflow blueprint catalog are [dashboard](/docs/dashboard.md) product flows. Start from the project home in the browser — there is no public API for the onboarding wizard itself.
- **Public API** `project API key`: The HTTP pack and template catalogs that power onboarding are also available on the Public API at `GET /v1/webhooks/http-packs` and `GET /v1/webhooks/templates` if you want to script the same selections from code.
- **CLI / SDK**: The CLI and SDK expose the template catalog (`hooksbase templates list`, `client.templates.list()`) but not the onboarding wizard itself.

## Workflow blueprints

The dashboard ships a fixed blueprint catalog rather than a user-defined workflow builder. The current catalog covers:

- inbound HTTP to your app
- inbound email to your app
- form submissions to your app
- queue handoff patterns (SQS, Pub/Sub)
- object storage / journal patterns
- scheduled background triggers

Availability is tier-aware, so the dashboard can show the full catalog while marking paths that require a plan upgrade. Destination and follow-up resource gates still apply: SQS and object-storage destinations require Pro+, and recurring schedule creation requires Starter+. Blueprints do not lock you in — once the webhook is provisioned, you can reconfigure destinations, transforms, and schedules independently of the path you started from.

## Validation flow

Onboarding validation is not a no-op check. Hooksbase actually synthesizes a source-specific sample payload and runs it through the same routing, transform, and outbound execution logic used by the live runtime.

Behavior that matters:

- HTTP paths can reuse HTTP pack sample generation
- email, form, and scheduled paths use the same envelope shapes as the live source channels
- successful validation marks onboarding completed and records `validatedAt`
- switching the selected path clears the tracked webhook and validation timestamp
- restarting onboarding does not delete any webhook or schedule resources

Related Public API routes:

- `GET /v1/webhooks/http-packs`
- `GET /v1/webhooks/templates`

The onboarding wizard itself is a dashboard-only flow — there are no public API routes for the onboarding state or validation step.

## Common mistakes

- Expecting onboarding restart to clean up already-created resources.
- Assuming validation is available for locked or archived webhook states.
- Treating onboarding as a replacement for understanding the actual webhook lifecycle.