Skip to main content
Ask your AI

Create Your Own Destination

This guide shows how to build a custom walkerOS destination.

The destination interface​

A destination is an object that implements the Destination.Instance interface from @walkeros/core. The most important property is the push function, which is called for every event.

interface Instance<T extends TypesGeneric = Types> {
  config: Config<T>;
  push: PushFn<T>;
  type?: string;
  env?: Env<T>;
  init?: InitFn<T>;
  pushBatch?: PushBatchFn<T>;
  on?: On.OnFn;
  setup?: SetupFn<Config<T>, Env<T>>;
  destroy?: DestroyFn<Config<T>, Env<T>>;
}

T bundles the destination's own types: Destination.Types<Settings, Mapping, Env>.

The push function​

The push function sends the event to your service. It receives the event and a context object.

type PushFn<T extends TypesGeneric = Types> = (
  event: WalkerOS.Event,
  context: Destination.PushContext<T>,
) => WalkerOS.PromiseOrValue<void | unknown>;

The push context contains:

  • config: Destination configuration with settings
  • env: Environment with window, document, etc.
  • logger: Logger instance
  • id: Unique destination identifier
  • data: Pre-computed data from mapping
  • rule: The matching mapping rule for this event
  • ingest: Optional request metadata from source
  • collector: The collector instance
  • reportError: Reports an error raised outside push, such as an SDK client's 'error' event, optionally for one event

Example: A simple webhook destination​

This example destination sends events to a webhook URL.

import {
  networkErrorMessage,
  StepError,
  type Destination,
} from '@walkeros/core';

// 1. Define your settings and bundle your types
interface WebhookSettings {
  url: string;
}

type Types = Destination.Types<WebhookSettings>;

// 2. A missing setting is a failure, never a silent return
function requireUrl(config: Destination.Config<Types>): string {
  const url = config.settings?.url;
  if (!url)
    throw new StepError('Webhook needs settings.url', { code: 'config' });
  return url;
}

// 3. Create the destination object
export const destinationWebhook: Destination.Instance<Types> = {
  type: 'webhook',
  config: {},

  // init fails when the destination cannot start
  init({ config }) {
    requireUrl(config);
  },

  async push(event, { config, rule }) {
    // A rule with silent: true sends nothing; the push still returns normally
    if (!rule?.silent) {
      // 4. Send the event and await it: a network failure is a StepError,
      //    and fetch resolves on an error status
      let response: Response;
      try {
        response = await fetch(requireUrl(config), {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(event),
        });
      } catch (err) {
        throw new StepError(networkErrorMessage(err), {
          code: 'transport',
          cause: err,
        });
      }
      if (!response.ok)
        throw new StepError(`HTTP ${response.status}`, {
          code: 'transport',
          status: response.status,
        });
    }
  },
};

Reporting failures​

A destination reports a failure by throwing. A push that returns normally counts as delivered, so it must not return early when it could not send, and it must await every call it makes: a call that is not awaited can fail after the push has already been counted.

Throw a StepError from @walkeros/core with a code, and optionally the HTTP status and retryable. The collector turns the throw into a failed push with that reason, counts it in the destination's failed counter, adds the event to the dead-letter queue and writes one ERROR line per cause and minute.

  • config - a required setting is missing or invalid (not retryable)
  • missing-input - the event has nothing this destination can send (not retryable)
  • vendor-not-loaded, vendor-not-ready, vendor-timeout - the vendor script is missing, not ready yet or too slow
  • transport - the request failed; a 429 and a 5xx status are retryable, other 4xx statuses are not

A TypeError, RangeError or ReferenceError is a runtime failure: a fault in step or flow code that a retry repeats, so it is not retryable. Node's fetch failed error stays a retryable transport failure, because it carries the network error's code on its cause. A failed fetch in the browser is a TypeError without that code, so throw network failures as a StepError with the code transport, as sendWeb and sendServer do. The conformance kit checks this: a destination that lets a raw fetch error escape fails its network check.

Any other throw is a transport failure. retryable tells a server source whether to ask the producer to resend the message. Keep payload data out of the error message; put a vendor response on the error's body, which is never logged.

A value that cannot be mapped is not a failure of the event: drop that field, send the event and report the problem once with reportCause from @walkeros/core.

init follows the same rule. It throws a StepError when the destination cannot start, such as a missing setting or a blocked vendor script, and it does not return false. A destination with a consent requirement is initialized only once consent is granted, and an init that does not settle within the destination's config.timeout (10 seconds by default) fails the waiting pushes with the timeout code.

Rule options every destination honours​

A destination honours rule.silent: a rule with silent: true sends no event of its own and only runs the side effects the rule maps, such as an identify. Skip the send with a condition rather than an early return, as in the example above. A silent rule whose side effects resolve to nothing sends nothing, counts as delivered and writes one DEBUG line that names the call and the mapping key, never the value.

Vendor scripts​

A web destination that loads a vendor script uses loadVendor from @walkeros/web-core and passes it the document of its env (getEnv(env).document, the page's own by default), so a simulation with a mock env never touches a real page. It injects the script once per page and fails with vendor-not-loaded, vendor-not-ready or vendor-timeout, so a blocked script shows as failed pushes instead of lost events.

Conformance test​

@walkeros/collector/dev exports conformance, a test kit that runs a destination against a real collector and checks, among others, that init throws a config error naming each required setting, that a failing send is reported, that a failure never leaks event data into a log line, that a silent example sends nothing and, for a vendor script, that a revoked consent reaches the vendor. Call it from a Jest test on real timers with the destination, its step examples, its settings schema, minimal valid settings, the package root and the profile that matches the destination: http for a destination that calls fetch, sdk-env for a server SDK, web-sdk for a web SDK started in init, vendor-global for a vendor script that defines a global, or socket. A browser profile (web-sdk, vendor-global) also needs the page option, imported from @walkeros/web-core/dev; without it the test fails and names that import.

Every destination test also passes minimal: the package's examples.minimal ({ settings: { ... } }), exported from src/examples/minimal.ts (per export: src/<export>/examples/minimal.ts), with only the settings the schema requires, plus any that init refuses to start without under the example's config. A server destination's minimal example maps credential settings to secret names in secrets, and a web destination that loads its script only on request also sets config: { loadScript: true }. The kit composes the minimal example into the integrated code and the flow file a quickstart shows, and requires it to deliver one public example. A package with several exports passes exportName and exportExamples instead; a package without a minimal example passes withoutMinimal: '<reason>'. A test with neither option fails, and so does one whose option disagrees with the published file. The conformance test template shows the call. A "one of these settings" rule is stated as anyOf in the settings schema.

Each failure the destination reports also ships as a step example: public: false, the outcome the push result reports (such as { status: 'failed', code: 'missing-input' }) and a description of when it happens. The package's docs page lists it under "When it fails" with that description; a failure example without one fails the docs build. See step examples.

Run the failure examples through runExamples from @walkeros/collector/dev in one of the package's tests, for example next to the conformance call: it compares each example's outcome with the push result. conformance does not do that for every profile, and never for http, so without such a test a wrong outcome still passes and is published:

import { runExamples } from '@walkeros/collector/dev';
import { destinationWebhook } from '..';
import { examples } from '../dev';

it('reports a rejected event', async () => {
  const { rejectedEvent } = examples.step;
  await runExamples(
    'destination',
    destinationWebhook,
    { rejectedEvent },
    { settings: examples.minimal.settings },
  );
});

The pushBatch function (optional)​

When the destination's config sets batch (see Batch scheduling), the collector buffers events and calls pushBatch once per flush instead of push per event. batch.entries holds one entry per event with its event, mapped data, rule, ingest and respond. Without pushBatch, every event goes to push, the batch setting has no effect and the collector logs one ERROR line when it registers the destination.

If pushBatch throws or rejects, every entry goes to the destination's dead-letter queue and counts as failed. To report single rows, resolve { failed: [{ index, error }] } with indices into batch.entries: only those entries fail. A batched event answers queued with the reason batch, so a server source acknowledges it when it is queued. A batch flushes after the elb calls that filled it have resolved, so a failed flush shows in the destination's failed counter, the dead-letter queue and one ERROR line, but the producer's message is not redelivered. A walker flush command flushes all pending batches at once. Pending batches are flushed at shutdown: the collector waits up to 5 seconds per flush and logs one that takes longer as failed.

Schemas​

A published destination exports JSON Schemas of its settings and mapping from src/dev.ts, usually written with Zod and converted with zodToSchema from @walkeros/core/dev. walkeros validate, the MCP tools and the docs read them from the package's walkerOS.json (see Package convention). The Meta Pixel destination is a complete example.

The on method (Optional)​

The optional on method lets your destination respond to collector lifecycle events, for example to handle consent changes or session management. Cleanup belongs in destroy.

The collector calls on once the destination is initialized, with or without an init method; deliveries that arrive earlier wait and reach it then, in order. A destination with a consent requirement is initialized only once that requirement is met (see Gate a destination with consent).

Available Events​

  • consent, user, globals, custom, config - The matching walker command changed collector state; context.data holds the values the command set
  • run - The collector started or received walker run
  • ready, session - A walker ready or walker session command (the session source sends session); they carry no data

The handler may be async. For consent, user, globals and custom, the collector waits for the handler to settle, up to config.timeout (10 seconds by default), before it pushes events to the destination. If the handler does not settle in that time, or rejects, the collector logs one ERROR line and holds the destination's events for one more config.timeout: the push result lists them as queued with the reason held, and a walker run discards them. A push after that window retries a delivery whose handler rejected. A handler that timed out and is still running gets no new delivery until it settles, and one that never settles gets none. Until a delivery succeeds, the held events and every later one fail with the code blocked. Lifecycle events are awaited too but hold no events, and they can reach the handler while it is still busy with a state update. The full rules are in State delivery.

export const destinationWithConsent: Destination.Instance<Types> = {
  type: 'webhook-consent',
  config: {},

  on(type, context) {
    if (type === 'consent') {
      // context.data holds the consent values the command set
      console.log('Consent updated:', context.data);
    }
  },

  push(event) {
    console.log('Event:', event);
  },
};

Setup lifecycle (optional)​

Components may implement an optional setup() lifecycle to provision external resources (BigQuery datasets, Pub/Sub topics, SQLite tables, webhook registrations) before the runtime processes events. Setup runs only when an operator invokes walkeros setup <kind>.<name>; the runtime never calls it.

Provisioning therefore stays off the event path. Production flows can ship with restricted runtime credentials (write-only), while an operator runs setup once per environment with elevated credentials (create).

The same lifecycle applies to sources, destinations, and stores. Transformers are pure functions and have no setup.

Behavior​

  • Setup is opt-in via config.setup in the flow config. The CLI invocation requires it to be true or an object; false or omitted means the operator's setup invocation is a narrated skip.
  • Idempotency is the package's responsibility. Re-running setup against a fully provisioned environment is a safe no-op.
  • walkeros setup runs init first and gives setup the config init returns, if any; when init throws or returns false, the command fails with the reason and setup does not run. destroy runs after setup.
  • Structured JSON output is opt-in via --json (e.g. walkeros setup <kind>.<name> --json). In normal mode the CLI narrates the action and never splices a JSON envelope into the output, even if setup() returns a value. The opt-in setup behavior and idempotency are independent of --json.

Example: a destination with setup​

import type { Destination } from '@walkeros/core';

interface BigQuerySettings {
  projectId: string;
  datasetId: string;
  tableId: string;
}

export const destinationBigquery: Destination.Instance<
  Destination.Types<BigQuerySettings>
> = {
  type: 'bigquery',
  config: {},

  async setup({ config }) {
    const { settings } = config;
    if (!settings) return;
    // Create dataset and table if missing. Idempotent: re-running is a no-op.
    // Return any structured result the operator may want to inspect.
    return {
      datasetCreated: settings.datasetId,
      tableCreated: settings.tableId,
    };
  },

  push(event, { config }) {
    // Hot path: only writes rows, never creates resources.
  },
};

A flow config opts in via config.setup, here for the BigQuery destination of @walkeros/server-destination-gcp:

{
  "destinations": {
    "bigquery": {
      "package": "@walkeros/server-destination-gcp",
      "config": {
        "setup": true,
        "settings": {
          "projectId": "my-proj",
          "datasetId": "events",
          "tableId": "raw"
        }
      }
    }
  }
}

Then the operator runs:

walkeros setup destination.bigquery

See also​

Using your destination​

To use your custom destination, add it to the destinations object in your collector configuration.

import { startFlow } from '@walkeros/collector';
import { destinationWebhook } from './destinationWebhook';

const { elb } = await startFlow({
  destinations: {
    myWebhook: {
      code: destinationWebhook,
      config: {
        settings: {
          url: 'https://api.example.com/events',
        },
      },
    },
  },
});

Environment dependencies (testing)​

The env parameter injects external APIs and SDKs into your destination, so you can test its logic without making actual API calls or requiring real browser globals.

Use cases:

  • Mock external SDKs (Google Analytics, Facebook Pixel, AWS SDK)
  • Test without network requests
  • Simulate different API responses
  • Run tests in any environment (Node.js, browser, CI)

Defining an Environment​

Define the external dependencies your destination needs:

// types.ts - Web destination
import type { DestinationWeb } from '@walkeros/web-core';

export interface Env extends DestinationWeb.Env {
  window: {
    gtag: (command: string, ...args: unknown[]) => void;
  };
}

// types.ts - Server destination
import type { DestinationServer } from '@walkeros/server-core';
import type { BigQuery } from '@google-cloud/bigquery';

export interface Env extends DestinationServer.Env {
  BigQuery?: typeof BigQuery;
}

Using Environment in Your Destination​

Add Env as the third type of your Types bundle for type safety, then access env in init or push:

import type { Destination } from '@walkeros/core';
import type { DestinationWeb } from '@walkeros/web-core';
import { getEnv } from '@walkeros/web-core';

interface Settings {
  /* ... */
}
interface Mapping {
  /* ... */
}
interface Env extends DestinationWeb.Env {
  window: { customAPI: (event: string) => void };
}

// Env is the third type of the bundle
type Types = Destination.Types<Settings, Mapping, Env>;

export const destination: DestinationWeb.Destination<Types> = {
  type: 'custom',
  config: {},

  async init({ config, env }) {
    // Initialize SDK using env, falls back to real APIs
    const { window } = getEnv<Env>(env);
    window.customAPI('init');
    return config;
  },

  push(event, { config, env }) {
    const { window } = getEnv<Env>(env);
    window.customAPI(event.name);
  },
};

Creating Test Environments​

Create reusable mock environments in an examples/env.ts file:

// examples/env.ts
import type { Env } from '../types';

const noop = () => {};

export const push: Env = {
  window: {
    customAPI: noop,
  },
};

// Call paths that simulate records
export const simulation = ['call:window.customAPI'];

Export from your examples index:

// examples/index.ts
export * as env from './env';

Using in Tests​

Tests push events through startFlow with this env and compare the recorded calls with your step examples, as in Using examples in tests.

Key points:

  • Production: No env needed, uses real APIs (window, fetch, SDKs)
  • Testing: Provide env with mocks for isolated testing
  • Type Safety: Env in your Types bundle types env in init and push
  • Fallback: getEnv(env) automatically uses real APIs if env not provided
  • Reusable: Store mock environments in examples/env.ts for consistency
  • Simulate: walkeros push --simulate runs the destination with examples.env.push and refuses a destination that has none, so it never calls the real vendor. Next to it, export simulation, the call paths that carry the vendor request (for example ['sendServer'] or ['call:PubSub.topic.publishMessage']), which simulate records and prints
  • Keep injected clients: when init builds an SDK client, reach it through env and create one only when none is injected, so the mock env reaches the request call

Package convention​

Every walkerOS package includes machine-readable metadata for tooling and discovery.

walkerOS field in package.json​

{
  "walkerOS": { "type": "destination", "platform": "web" },
  "keywords": ["walkerOS", "walkerOS-destination"]
}
FieldRequiredDescription
walkerOSYesObject with type and platform metadata

Build-time generation​

Use buildDev() from the shared tsup config to auto-generate walkerOS.json:

import { buildDev } from '@walkeros/config/tsup';

This file contains your package's JSON Schemas and examples, so MCP tools and the CLI can validate configurations without installing your package.

buildDev() fails the build when the package publishes no schemas.settings. A package with two or more walkerOS.exports also exports exportExamples and exportSchemas from src/dev.ts, each listing exactly those exports, the default included, with settings in every exportSchemas entry; a package with fewer exports sets neither.

Optional: Hints​

Packages can export a hints record from src/dev.ts with short notes that schemas and examples do not cover, such as authentication methods, storage behavior, or troubleshooting tips. Hints are serialized into walkerOS.json and surfaced via MCP tools. See the walkeros-create-destination skill for details.

Publishing checklist​

  • walkerOS field in package.json
  • Keywords include walkerOS and walkerOS-destination
  • buildDev() in tsup.config.ts
  • schemas.settings exported from src/dev.ts (per export for multi-export packages)
  • dist/walkerOS.json generated on build
  • src/examples/minimal.ts exported as examples.minimal (or withoutMinimal with a reason in the conformance test)
  • A failure example (public: false, outcome, description) for each failure the destination reports
  • A test that runs the failure examples through runExamples
  • npm run test passes
  • npm run lint passes
💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)