Web API Destination for walkerOS

Source Code • NPM Package

The API destination allows you to send events to any HTTP endpoint with customizable data transformation and transport methods.

walkerOS follows a source → collector → destination architecture. This API destination receives processed events from the walkerOS collector and sends them to your custom API endpoint, enabling integration with internal analytics systems, data warehouses, or custom business logic that requires real-time event data.

Installation

npm install @walkeros/web-destination-api

Configuration

| Name | Type | Description | Required | Example | | ----------- | ------------------------------ | ------------------------------------------------ | -------- | ------------------------------------------------------------------------- | | url | string | The HTTP endpoint URL to send events to | Yes | 'https://api.example.com/events' | | headers | Record<string, string> | Additional HTTP headers to include with requests | No | { 'Authorization': 'Bearer token', 'Content-Type': 'application/json' } | | method | string | HTTP method for the request | No | 'POST' | | transform | function | Function to transform event data before sending | No | (data, config, mapping) => JSON.stringify(data) | | transport | 'fetch' \| 'xhr' \| 'beacon' | Transport method for sending requests | No | 'fetch' |

Quick Start

Configure in your Flow JSON:

{
  "version": 1,
  "flows": {
    "default": {
      "web": {},
      "destinations": {
        "api": {
          "package": "@walkeros/web-destination-api",
          "config": {
            "settings": {
              "url": "https://api.example.com/events",
              "method": "POST",
              "headers": { "Authorization": "Bearer your-token" }
            }
          }
        }
      }
    }
  }
}

Or programmatically:

import { startFlow } from '@walkeros/collector';
import { destinationAPI } from '@walkeros/web-destination-api';

const { elb } = await startFlow({
  destinations: [
    {
      destination: destinationAPI,
      config: {
        settings: {
          url: 'https://api.example.com/events',
          method: 'POST',
          headers: { Authorization: 'Bearer your-token' },
        },
      },
    },
  ],
});

Usage

Advanced Usage with Transform

import { startFlow } from '@walkeros/collector';
import { destinationAPI } from '@walkeros/web-destination-api';

const { elb } = await startFlow({
  destinations: [
    {
      destination: destinationAPI,
      config: {
        settings: {
          url: 'https://api.example.com/events',
          transport: 'fetch',
          transform: (event, config, mapping) => {
            return JSON.stringify({
              timestamp: Date.now(),
              event_name: `${event.entity}_${event.action}`,
              properties: event.data,
              context: event.context,
            });
          },
        },
      },
    },
  ],
});

Examples

Sending to Analytics API

{
  "destinations": {
    "analytics": {
      "package": "@walkeros/web-destination-api",
      "config": {
        "settings": {
          "url": "https://analytics.example.com/track",
          "method": "POST",
          "headers": {
            "Content-Type": "application/json",
            "X-API-Key": "your-api-key"
          }
        }
      }
    }
  }
}

Using Beacon Transport

For critical events that need to be sent even when the page is unloading:

{
  "destinations": {
    "critical": {
      "package": "@walkeros/web-destination-api",
      "config": {
        "settings": {
          "url": "https://api.example.com/critical-events",
          "transport": "beacon"
        }
      }
    }
  }
}

Custom Data Mapping

Use mapping rules to control which events are sent:

{
  "destinations": {
    "api": {
      "package": "@walkeros/web-destination-api",
      "config": {
        "settings": { "url": "https://api.example.com/events" },
        "mapping": {
          "entity": {
            "action": { "data": "data" }
          }
        }
      }
    }
  }
}

Transport Methods

• fetch (default): Modern, promise-based HTTP requests
• xhr: Traditional XMLHttpRequest for older browser compatibility
• beacon: Uses Navigator.sendBeacon() for reliable data transmission during page unload

Type Definitions

See src/types/ for TypeScript interfaces.

Related

• Website Documentation
• Destination Interface

Contribute

Feel free to contribute by submitting an issue, starting a discussion, or getting in contact.

License

This project is licensed under the MIT License.