White-label (connectUrl)

Create an endpoint on Webhooks with Create endpoint — use a public https URL; deliveries to private or loopback addresses are rejected at delivery time (dead-lettered). The Save your signing secret screen reveals the signing secret exactly once. These are the events an endpoint can subscribe to:

• session.completed
• session.failed
• session.expired
• session.auth_required
• extraction.completed
• extraction.failed
• credit.low
• credit.exhausted
• auto_recharge_failed

Every delivery carries exactly three headers: Odynn-Signature: t=<unix>,v1=<hex>[,v1prev=<hex>], Odynn-Event-Id, and Content-Type: application/json. Verify the HMAC-SHA256 signature over `${t}.${rawBody}` with a constant-time compare before trusting anything:

// Odynn-Signature: t=1784549021,v1=5f8a…   (+ ",v1prev=…" during rotation grace)
const [t, v1, v1prev] = parseOdynnSignature(req.headers["odynn-signature"]);

const expected = createHmac("sha256", signingSecret)
  .update(`${t}.${rawBody}`)   // rawBody = the exact request body bytes
  .digest("hex");               // lowercase hex

const valid =
  timingSafeEqual(expected, v1) ||
  (v1prev !== undefined && timingSafeEqual(expected, v1prev));

// Ack with any 2xx within 15 s, then process asynchronously.
// Dedupe on the Odynn-Event-Id header — it is stable across retries.

A delivery succeeds only on a 2xx within the 15-second per-attempt timeout — return 200 immediately and process the event async. Failures retry on a backoff of 30 s → 2 m → 10 m → 1 h across 5 total attempts, then the delivery is dead-lettered. The exact cadence is platform-configured and can vary by environment — design for retries arriving hours later, not for a fixed schedule. Retries resend a byte-identical body and signature — the t timestamp does not advance — so do not enforce a tight replay tolerance, and dedupe on Odynn-Event-Id instead.

When you rotate a secret (Rotate signing secret on the endpoint's Manage page), deliveries are signed with both secrets for the grace window (default 24 hours): v1 is the new secret, v1prev the old one — accept either. Use Send test delivery to push a synthetic webhook.test event through the real signed pipeline before going live.

Instead of asking the user to sync again, POST /v1/sessions/refresh re-pulls a connected account and only bills when data is actually delivered. Today a refresh either answers from cache (free) or asks the user to sign in again through a one-time link — a new sync at your per-sync price that counts toward your sync cap. maxDataAgeSeconds sets how fresh is fresh enough: a recent-enough cached extraction answers synchronously with status: "cached", still fires a session.completed webhook with cacheHit: true, and is not billed.

Coming soon — silent refresh. Once on-device cookie capture ships, refreshes for users who installed the full Connect app will complete in the background with no user interaction for a flat 1 credit — a fraction of a full sync — and will not count toward your sync cap. Nothing about the request, response, or webhooks below changes when it arrives.

POST /v1/sessions/refresh
Idempotency-Key: 9d1f7c3a-2e6b-4a8d-b5c0-1f4e7a9d2b6c

{ "providerId": "aadvantage", "userId": "user-123", "maxDataAgeSeconds": 21600 }

{
  "sessionId": "ses_r3fR2kQ9xW1p",
  "status": "refreshing",
  "expectedCompletionAt": "2026-07-20T12:08:41.000Z"
}

The default limit is 5 successful refreshes per user + provider per minute — a 429 carries Retry-After; cache hits and un-tapped re-auth prompts do not consume the window. Behind the 202, a four-tier cascade runs: fresh cache → server-side silent replay (coming soon) → silent wake of the user's installed Connect app (coming soon) → user-tap re-auth. When they ship, tiers two and three will deliver a normal session.completed with no user involvement; today a cache miss goes straight to the last tier.

Only the last tier needs the user. It fires a session.auth_required webhook — your playbook:

{
  "id": "evt_9Rt4wY2kM7cQ",
  "type": "session.auth_required",
  "tenant": "ten_2wXcV5bN8mK1",
  "occurredAt": "2026-07-20T12:04:02.000Z",
  "data": {
    "sessionId": "ses_r3fR2kQ9xW1p",
    "providerId": "aadvantage",
    "userId": "user-123",
    "connectUrl": "https://connect.odynn.com/link/horizon-travel/ses_c1xN4pV7mB2d",
    "urlsExpireAt": 1784550842000,
    "lastSuccessfulSyncAt": 1784462621000,
    "occurredAt": 1784549042000
  }
}

• connectUrl non-null — prompt the user (your own push or in-app nudge) to tap it before urlsExpireAt; the URLs live 30 minutes. Completing the tap delivers session.completed, billed as a sync at your per-sync price — the user re-authenticated, so it is a new sync.
• connectUrl: null — the window closed unbilled; start over with a plain POST /v1/sessions (a new sync, at sync rates).

How much refresh you get depends on the path you used to connect:

Refreshing a whole population? POST /v1/sessions/refresh/bulk takes a selector (all_active, an explicit user_ids list, or a named segment) and returns a batchId; read progress with GET /v1/sessions/refresh/bulk/:batchId. There is no batch-level webhook — per-user results arrive on your normal session.* events, and items can be skipped as already_refreshing, rate_limited, or payment_required.

By default the Connect surface your users see carries the Odynn / TravelerDNA identity. Flip Enable branding on the Branding page (admin) to theme it with your display name, colors, logo and splash assets, font, and support link — then Save & Publish. It is entirely self-serve and applies on the app's next launch; no need to contact Odynn.

Branding themes the connectUrl Connect-app surface only. It never touches your own Native SDK embed, and the App Store name stays TravelerDNA. Partial branding degrades gracefully — anything you leave unset falls back to the built-in default, so you can publish a display name and a primary color and stop there.

Pricing is denominated in credits: 1 credit = 1¢ USD. A full sync (a completed POST /v1/sessions flow) costs your plan's per-sync rate, a refresh that needs the user to sign in again costs the per-sync rate, a cache hit is free, and plain API calls are free. Silent refresh (coming soon) will cost a flat 1 credit. Balances and rates live on Billing (admin), where Buy credits tops up ($1 buys 100 credits) and Auto-recharge keeps the balance above a threshold automatically.

Two 402 responses gate billable work before it starts: payment_required (balance cannot cover the action — details carries priceCredits and totalCredits; top up or wait for auto-recharge) and tier_cap_reached (the plan's monthly sync cap is exhausted — details carries used and cap; a refresh that ends in the user signing in again counts as a sync). Treat both as retryable-after-action, not as errors to hammer.

Don't wait for the 402: subscribe a webhook endpoint to credit.low (fires when the balance crosses the warning threshold, 7,500 credits by default), credit.exhausted (the balance can no longer cover one sync), and auto_recharge_failed (the saved card declined or the monthly cap was hit).

Start on Pay-as-you-go. Evaluate on the Pay-as-you-go tier: real syncs against real providers at 15 credits per sync, with no monthly commitment. When your volume justifies it, move to Core or Pro from the plan picker on Billing — the upgrade goes through a Stripe Checkout and starts as soon as payment completes (changes between committed plans take effect at the next renewal).

Idempotency. Send an Idempotency-Key header (any unique string, e.g. a UUID) on mutating calls — session create, refresh, key create, webhook mutations. A replay within 24 hours returns the original response with Idempotent-Replayed: true.

Rate limits. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 adds Retry-After in seconds. Back off until then instead of retrying hot.

Errors. Every error is { "error": { "code", "message", "details", "requestId" } } — branch on code, and quote requestId when you contact support. Resources you don't own return 404, never 403, so a 404 can mean “not yours” as well as “not found”.

Sessions are disposable. Mint a fresh session per connect attempt; never reuse, share, or persist the URLs — they are single-use and expire in minutes.