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 settingsenv: Environment with window, document, etc.logger: Logger instanceid: Unique destination identifierdata: Pre-computed data from mappingrule: The matching mapping rule for this eventingest: Optional request metadata from sourcecollector: The collector instancereportError: Reports an error raised outsidepush, 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 slowtransport- the request failed; a429and a5xxstatus are retryable, other4xxstatuses 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 matchingwalkercommand changed collector state;context.dataholds the values the command setrun- The collector started or receivedwalker runready,session- Awalker readyorwalker sessioncommand (the session source sendssession); 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.
Example: Consent-Aware Destination
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.setupin the flow config. The CLI invocation requires it to betrueor an object;falseor 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 setuprunsinitfirst and givessetupthe configinitreturns, if any; wheninitthrows or returnsfalse, the command fails with the reason and setup does not run.destroyruns aftersetup.- 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 ifsetup()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.bigquerySee also
- walkeros setup CLI command for the operator-facing command, options, and exit codes.
- Create your own source for source setup.
- Stores for store setup and lifecycle ordering.
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
envneeded, uses real APIs (window, fetch, SDKs) - Testing: Provide
envwith mocks for isolated testing - Type Safety:
Envin yourTypesbundle typesenvininitandpush - Fallback:
getEnv(env)automatically uses real APIs if env not provided - Reusable: Store mock environments in
examples/env.tsfor consistency - Simulate:
walkeros push --simulateruns the destination withexamples.env.pushand refuses a destination that has none, so it never calls the real vendor. Next to it, exportsimulation, 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
initbuilds an SDK client, reach it throughenvand 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"]
}| Field | Required | Description |
|---|---|---|
walkerOS | Yes | Object 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
-
walkerOSfield in package.json - Keywords include
walkerOSandwalkerOS-destination -
buildDev()in tsup.config.ts -
schemas.settingsexported fromsrc/dev.ts(per export for multi-export packages) -
dist/walkerOS.jsongenerated on build -
src/examples/minimal.tsexported asexamples.minimal(orwithoutMinimalwith 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 testpasses -
npm run lintpasses