Key Concepts

A quick reference for the objects you'll touch in the dashboard, API, and CLI.

Organization

An organization (org) is the top-level container for all your hookstream resources. When you sign up, an org is auto-provisioned. Sources, destinations, connections, events, metrics, and team members all belong to an org.

• ID format: org_<hex>
• Management: invite teammates and manage roles from Settings > Team in the dashboard.

Project

Each org has one or more projects (e.g. production, staging). Projects provide data isolation — sources, destinations, connections, and events are all scoped to a project, and API keys are issued per project.

• ID format: env_<hex>
• Switch the active project from the sidebar dropdown in the dashboard.

The API and database still use the legacy name environment (for example /v1/environments, env_id response fields). The dashboard and docs call them projects — it's a UI rename, not a schema change.

Source

A source is a webhook ingestion endpoint. Each source has a unique URL:

text
https://hookstream.io/v1/ingest/<source_id>

Sources accept any HTTP method and can be configured with signature verification (HMAC-SHA256, SHA-1, Standard Webhooks), IP allowlisting, and deduplication. Pick from 15+ provider templates (Stripe, GitHub, Shopify, and more) for one-click setup.

Destination

A destination is where events get delivered. hookstream supports 8 provider types:

• HTTP / Webhook — any endpoint that accepts JSON
• AWS SQS — via SigV4 and crypto.subtle
• AWS S3 — object storage delivery
• AWS EventBridge — event buses
• GCP Pub/Sub — with service account JWT auth
• Kafka — via Confluent REST Proxy
• RabbitMQ — via HTTP Management API
• WebSocket — broadcast to connected clients

Each destination has its own retry policy, circuit breaker, and dead letter queue. See Destinations for the full matrix.

Connection

A connection routes events from a source to a destination. Connections can have:

• Content-based filters — selectively route events based on payload fields.
• JSONata transforms — reshape payloads before delivery.
• Schema validation — reject or warn on malformed events.

Multiple connections can reference the same source, enabling fan-out.

Event

An event is a single webhook request received by a source. Events store the full HTTP method, headers, body, query parameters, and metadata (source IP, content length, etc). Events follow a simple lifecycle:

text
received -> processing -> delivered | failed

Delivery Attempt

A delivery attempt is a single try to send an event to a destination. Each attempt records:

• HTTP status code
• Response body (truncated)
• Latency in milliseconds
• Error message (if any)

Failed attempts trigger retries according to the destination's retry policy. See Delivery Attempts for the state machine.

API Key

API keys authenticate machine clients to the hookstream API. Keys are scoped to a project and look like:

text
hs_live_<64 hex>   # production
hs_test_<64 hex>   # testing

The plaintext key is shown once at creation — only the SHA-256 hash is stored. If you lose it, create a new key and rotate.

Next Steps