Core concepts

Events & webhooks

Dreambase talks to services through webhook events. The platform POSTs an event to a service's webhook URL; the service acts on it and calls back into the Dreambase API to report status, logs, and outputs.

The webhook model

Every service definition registers a webhook URL. When something happens in a project — a service is added, a deployment is created, a function is called — the Dreambase API dispatches an event as an HTTP POST to that URL. The receiving service does the work asynchronously and reports back to the API.

Fire-and-forget, then call back

Services typically respond to the webhook immediately and do their real work in the background, then call back into the Dreambase API with the result. This keeps webhook responses fast and lets long operations (provisioning, health checks) run without blocking.

Event types

Services understand a common vocabulary of event names. The exact set a service handles depends on what it does, but the platform's integration services recognize:

  • WEBHOOK_CHALLENGE — a verification handshake (see below).
  • HEALTH_CHECK — check that a deployment is reachable and report its status.
  • DEPLOYMENT_CREATED — a new deployment was requested; provision and start it.
  • DEPLOYMENT_DELETED — a deployment record was removed; tear down its infrastructure.
  • DEPLOYMENT_STATUS_CHANGED— a deployment's status changed; react as needed. When a new deployment supersedes an older one, the old deployment is marked STOPPED (its record is kept) and this event is emitted so the service can reclaim the hosted resource.
  • DEPLOYMENT_ENV_CHANGED— a deployment's environment variables changed — for example, because a dependency it is connected to published new outputs; apply them (e.g. redeploy with the new values).
  • DOWNLOAD_STARTED— signals that a download/build of a service's sources has begun.
  • FUNCTION_CALL — invoke a named function the service exposes, with arguments.
  • SERVICE_ADDED — a service definition was added to a design.

The webhook challenge

When a webhook URL is first registered or verified, Dreambase sends a WEBHOOK_CHALLENGE event carrying a challenge value. The service must echo it straight back:

// Request from Dreambase
POST /<service>/webhook
{ "name": "WEBHOOK_CHALLENGE", "challenge": "abc123" }

// Expected response
{ "challenge": "abc123" }

Every platform service implements this handshake, which is how Dreambase confirms a webhook endpoint is live and owned by the right service.

Service tokens & scopes

Events carry a service token that the receiving service uses to authenticate its callbacks into the Dreambase API. Tokens are scoped: a service is granted only the permissions it needs — to read a deployment, resolve an environment variable, or post a status update, for example.

Treat tokens as secrets

Service tokens are never exposed in API responses except when explicitly requested, and webhook payloads should be verified before they are trusted. Handle tokens with the same care as any other credential.

A rich payload

Event payloads include the full context a service needs to act: the service, the deployment, the environment, and the design it belongs to. That is why a single HEALTH_CHECK or FUNCTION_CALL is enough for a service to do its job and report a precise result back.