Segment integration

Segment is a customer data platform: your product sends each user action (a "track call") to Segment once, and Segment fans it out to analytics, marketing and data tools. Many teams already have their whole event catalog flowing through it.

The Perkamo Segment integration (beta) lets you reuse that stream. Instead of writing new backend code to call Perkamo, you forward selected Segment events to a dedicated Perkamo endpoint. Perkamo maps each one onto a stable event key, runs your earning rules and returns points, levels, achievements and perks like any other trusted event.

How it fits together

1. Your product tracks an action once: analytics.track("Order Completed", ...).
2. A Segment destination function forwards the call to

POST /v1/integrations/segment.

1. Perkamo maps the name onto a dotted event key: Order Completed becomes

order.completed.

1. Your earning rules match on that key and award points, progress levels and

unlock perks.

1. Webhooks hand the resulting effects back to the systems

that fulfill them.

You write earning rules against the mapped keys, exactly as if your backend had called POST /v1/events directly.

What it solves

• No new instrumentation. Actions your product already tracks become

loyalty events. One track call powers analytics and rewards.

• Idempotent by construction. Segment retries deliveries; Perkamo uses the

Segment messageId as the transaction id, so a retried delivery can never award points twice.

• Trusted-source discipline. Forward server-side sources only. Browser-only

analytics events can be spoofed and should not become authoritative points or rewards.

Set up forwarding with a destination function

Perkamo mutation endpoints require a signed request, and Segment's plain webhook destination cannot compute signatures. Use a Segment destination function instead; it can. Create one in Segment (Connections, Catalog, Functions), paste the template below and set two function settings: perkamoServerKey (a server key with the events:write scope) and perkamoApiUrl (https://api.perkamo.com).

// Segment destination function: forward track/identify calls to Perkamo.
async function forwardToPerkamo(event, settings) {
  const body = JSON.stringify({
    type: event.type,
    userId: event.userId,
    event: event.event,
    messageId: event.messageId,
    properties: event.properties,
    traits: event.traits,
    timestamp: event.timestamp,
  });

  const timestamp = String(Math.floor(Date.now() / 1000));
  const path = "/v1/integrations/segment";
  const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
  const base = ["v1", timestamp, "POST", path, bodyHash].join(".");
  const signature =
    "v1=" +
    crypto.createHmac("sha256", settings.perkamoServerKey).update(base).digest("hex");

  const response = await fetch(settings.perkamoApiUrl + path, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-perkamo-api-key": settings.perkamoServerKey,
      "x-perkamo-timestamp": timestamp,
      "x-perkamo-signature": signature,
    },
    body,
  });

  if (!response.ok && response.status >= 500) {
    // Throwing makes Segment retry; messageId keeps the retry idempotent.
    throw new RetryError(`Perkamo responded ${response.status}`);
  }
}

async function onTrack(event, settings) {
  return forwardToPerkamo(event, settings);
}

async function onIdentify(event, settings) {
  return forwardToPerkamo(event, settings);
}

Forward only the event names you want to reward. A filter at the top of onTrack (or a Segment destination filter) keeps noise like Page Viewed out of your loyalty pipeline.

Event name mapping

The mapping is deterministic so the same Segment call always produces the same Perkamo event key:

The original display name is preserved in context.segment_event, and properties become the event context, available to your rules and visible on the customer timeline.

Verify the first event

1. Create a server key with the events:write scope in Settings, Server keys.
2. Deploy the function and send a test event from Segment's function editor.
3. Open the Perkamo console Testing page: the event appears with its mapped

key, the rule result and any unlocks.

1. Write or adjust an earning rule for the mapped key, then send the event

again with a new messageId and watch points apply.