​

Short links with click tracking and campaign attribution

​

1. What a short link is in Orbit

​

2. Auto-shorten inside a send

​

3. Explicit shortening — one-off links

curl -X POST https://api.orbit.devotel.io/api/v1/links \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/promo",
    "campaign_id": "cmp_may26"
  }'

import { Devotel } from '@devotel-orbit/node';

const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });

const link = await orbit.links.create({
  url: 'https://example.com/promo',
  campaign_id: 'cmp_may26',
});

console.log(link.data.short_url); // https://api.orbit.devotel.io/l/gH4kM2

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()

result = client.request(
    "POST",
    "/links",
    json_body={
        "url": "https://example.com/promo",
        "campaign_id": "cmp_may26",
    },
)
print(result["data"]["short_url"])  # https://api.orbit.devotel.io/l/gH4kM2

result := map[string]any{}
err := client.Request(
    context.Background(),
    "POST",
    "/links",
    nil, // no query params
    map[string]string{
        "url":         "https://example.com/promo",
        "campaign_id": "cmp_may26",
    },
    &result,
    "", // the SDK generates an idempotency key when empty
)

​

4. Branded short domains

1. Your tenant’s branded domain, if set. It must be a bare https:// (or http:// for staging) host with no path, query, or fragment — https://go.yourbrand.com, not https://go.yourbrand.com/landing. DNS must point to Orbit’s redirector with a valid TLS certificate and a served GET /l/:code route.
2. Platform default — https://api.orbit.devotel.io, resolved from DEVOTEL_SHORT_LINK_DOMAIN when an operator has provisioned a genuine vanity short host (e.g. https://orbt.to), then DEVOTEL_API_URL.

​

5. Click-quality signals — human vs scanner

• is_bot — true when the UA matches a signature, or the UA is missing entirely.
• quality_score — 1.0 confident human, 0.0 confident bot, 0.3 missing UA. A verified click means score >= 0.5.
• quality_reason — bot_user_agent, missing_user_agent, or null.

​

6. Campaign attribution and webhooks

• Per-campaign rollup: GET /api/v1/links/campaigns/{campaignId}/link-analytics returns totals (minted links, raw clicks, verified clicks, unique clicker recipients, attributed recipients), per-channel breakdown, and a top-links ranking — with derived unique_attribution_rate and verified_attribution_rate guards so a campaign with no clicks never divides by zero.
• Per-contact history: GET /api/v1/links/contacts/{contactId}/clicks closes the loop — the CDP engagement view answers “which links did THIS recipient tap,” newest first.
• Tenant-wide insights: GET /api/v1/links/insights bundles KPIs, top links, and a day-by-day click timeline in one call.

import crypto from 'node:crypto';

function parseSignatureHeader(header) {
  let t = null;
  const v1s = [];
  for (const part of (header ?? '').split(',')) {
    const eq = part.trim().indexOf('=');
    if (eq < 0) continue;
    const key = part.trim().slice(0, eq);
    const value = part.trim().slice(eq + 1);
    if (key === 't') t = value;
    else if (key === 'v1') v1s.push(value);
  }
  return { t, v1s };
}

function isSignatureValid(rawBody, header, secret) {
  const { t, v1s } = parseSignatureHeader(header);
  if (!t || v1s.length === 0) return false;

  // Replay protection: reject signatures older than 5 minutes.
  const ageSec = Math.floor(Date.now() / 1000) - Number(t);
  if (!Number.isFinite(ageSec) || ageSec < 0 || ageSec > 5 * 60) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`, 'utf-8')
    .digest('hex');
  const expectedBuf = Buffer.from(expected, 'hex');

  // Accept if ANY v1 candidate matches (covers a rotation grace window).
  return v1s.some((candidate) => {
    const candidateBuf = Buffer.from(candidate, 'hex');
    return (
      candidateBuf.length === expectedBuf.length &&
      crypto.timingSafeEqual(candidateBuf, expectedBuf)
    );
  });
}

// In your route handler (Express-style) — keep the raw body around for the HMAC:
app.post('/webhooks/orbit', (req, res) => {
  const header = req.headers['x-orbit-signature'] ?? req.headers['x-devotel-signature'];
  if (!isSignatureValid(req.rawBody, header, process.env.ORBIT_WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.rawBody);
  if (event.type === 'short_link.click') {
    // React only to verified taps — link-preview fetches arrive as bots.
    if (event.data.is_bot === false && event.data.quality_score >= 0.5) {
      // Push event.data.contact-level attribution into your CRM here.
    }
  }
  res.status(200).json({ received: true });
});

​

7. Tenant-level totals — the Insights → Link tracking rollup

• Per-campaign rollup (GET /api/v1/links/campaigns/{campaignId}/link-analytics) scopes every number to links whose mint carried that campaign_id — one campaign’s totals, channel breakdown, and top links.
• Tenant-level rollup (GET /api/v1/links/insights) is the operator’s “how is link traffic doing across everything” view. One call returns the summary KPI block (total links minted, raw and verified clicks in the window, unique clickers, average clicks per link), a top_links ranking, and a day-by-day timeline. The window is window_days (default 7, up to 90) and top_limit sizes the ranking; Insights → SMS click-through layers the channel-side view on top.

​

8. Landing pages

​

9. Error surface

​

Troubleshooting

• Links minted with the long platform default, not my branded domain. The tenant setting must be a bare https://host with no path/query/fragment — a value like https://go.yourbrand.com/page falls back to the default. Check the dashboard field or the warn log; after fixing, re-mint your links (existing short URLs keep resolving).
• Branded domain saved, but inbox/social previews still show the old host — or the links resolve to nothing. DNS hasn’t propagated yet after you pointed the host, or the record points somewhere that isn’t Orbit’s redirector. The mint base is set at save time, so pre-set mints keep the default host; wait for propagation, and verify the CNAME target with your ops contact before reusing branded links in an outbound send — a link minted on a host whose redirect doesn’t serve GET /l/:code is a dead tap for recipients.
• The branded-domain card rejects my value. Read the inline message — the usual causes are a path (/landing), a missing scheme, or a bare hostname without https://. A trailing slash is stripped silently; anything else is rejected so you never save a silently-ignored value.
• My campaign totals don’t add up to the tenant total on Insights → Link tracking. Tenant rollups include un-attributed links — one-off mints without campaign_id, plus auto-shortened sends where attribution arrives later. Scope with the campaign_id filter when you want a campaign-only cut; the residual gap is the working-as-designed un-attributed bucket.
• SMS body got longer with shorten_urls ON. Impossible after the net-shortening guard — the explicit opt-in path also refuses equal-or-longer swaps. If you saw growth on an older send, the link predates the guard; re-send and the current send pipeline will no-op on that URL.
• Click counts are inflated for a WhatsApp or SMS send. Filter on verified_clicks and quality_score >= 0.5 — link-preview fetches inflate raw clicks by design, because the redirect can’t distinguish a preview from a tap until it reads the user-agent.
• short_link.click webhook is absent for a free-text WhatsApp send. Template/broadcast sends carry no on-wire body (finalBody is empty — Meta renders the approved template at send time), so auto-track only fires for free-text bodies. For template clicks, the tracking has to live in the template’s approved URL, which is a Meta re-approval concern.