Integration guide

Quick start

You integrate with Omer Insight once. We connect the survey providers and send their confirmed events to your App. You supply the user identity, embed the wall and maintain your own user ledger. Your users do not need an Omer Insight Publisher account.

1. 01

   Create your App

   Register and verify your Publisher account, then open Apps → Create App. Every new App starts in test mode, including Apps created by an approved account.

2. 02

   Collect the credentials

   Open the App → General settings. Copy App code, App secret and the security hash. The Integration information tab contains examples, not a second set of credentials.

3. 03

   Save your settings

   Set the App name and user-facing currency in the editor. In Postback settings, save a public receiving URL. A main URL is required even if you configure separate event URLs.

4. 04

   Build the two connections

   Embed the wall for your signed-in users and implement a server endpoint for callbacks. These are separate connections: showing the wall does not automatically update your database.

5. 05

   Test before launch

   First test the receiving endpoint with Send test postback. Then add your test user ID or IP in General settings and verify the wall with that identity.

6. 06

   Request launch

   Save all changes, finish the checks below and click Request launch in the App editor. Only an administrator can change the App to live.

App code and secrets

Find these values in App → General settings. Use the credentials for the same App at both ends of the integration.

Embed the surveywall

Load the wall in an iframe on your authenticated user page. Use a stable ID from your own system; the same ID returns as user_id in callbacks. Do not generate a new ID on each visit.

<iframe
  src="https://offers.omerinsight.com/wall/en?app_id=YOUR_APP_CODE&ext_user_id=USER_123&secure_hash=SERVER_GENERATED_HASH"
  title="Omer Insight"
  style="width:100%;height:720px;border:0"
  allow="clipboard-write"
></iframe>

Replace YOUR_APP_CODE, USER_123 and SERVER_GENERATED_HASH. The PHP example builds and URL-encodes the link on your server; replace authenticatedUserId with your own session identity. The browser receives only the final URL. If your page uses a Content Security Policy, allow https://offers.omerinsight.com in frame-src. Verify survey navigation on the browsers or WebViews you support.

<?php
// In your authenticated page/controller. Never accept the user ID from a form.
$appCode = getenv('OMER_APP_CODE');
$appSecret = getenv('OMER_APP_SECRET');
if (!$appCode || !$appSecret) {
    throw new RuntimeException('Configure OMER_APP_CODE and OMER_APP_SECRET');
}
// Replace this with the ID from YOUR authenticated server-side session.
$userId = (string) $authenticatedUserId;
$query = http_build_query([
    'app_id' => $appCode,
    'ext_user_id' => $userId,
    'secure_hash' => md5($userId . '-' . $appSecret),
], '', '&', PHP_QUERY_RFC3986);
$wallUrl = 'https://offers.omerinsight.com/wall/en?' . $query;
?>
<iframe
  src="<?= htmlspecialchars($wallUrl, ENT_QUOTES, 'UTF-8') ?>"
  title="Omer Insight"
  style="width:100%;height:720px;border:0"
  allow="clipboard-write"
></iframe>

URL parameters

Receive postbacks

A postback is a server-to-server notification. Omer Insight sends an HTTP GET request to the URL saved in your App. Values replace the placeholders before sending. Your endpoint must work without a browser session or login cookie.

https://publisher.example.com/omer/postback?status={status}&trans_id={trans_id}&original_trans_id={original_trans_id}&user_id={user_id}&amount_usd={amount_usd}&amount_local={amount_local}&type={type}&test={test}&subid_1={subid_1}&subid_2={subid_2}&hash={secure_hash}

Placeholders

Postback types

All four event types are enabled. The main URL is required. Separate screenout, bonus and reversal URLs are optional; an empty separate URL uses the main URL. This lets you implement one endpoint that routes by type and status.

Verify the signature

Every callback includes X-Omer-Signature. Current App callbacks use GET: calculate HMAC-SHA256 with App secret over the exact full public URL, including the unchanged path and query string. Compare the lowercase hexadecimal digest using a constant-time comparison. Never sort, decode or rebuild the query before verification.

<?php
// Configure your PUBLIC origin, including scheme and non-default port.
// Do not trust a client-supplied Host or X-Forwarded-Proto header.
$publicOrigin = 'https://publisher.example.com';
$secret = getenv('OMER_APP_SECRET');
if (!$secret) {
    http_response_code(503);
    exit('Receiver not configured');
}
$method = $_SERVER['REQUEST_METHOD'];
$raw = file_get_contents('php://input');
$signed = $method === 'GET'
    ? $publicOrigin . $_SERVER['REQUEST_URI'] // exact path + query, no re-encoding
    : $raw;
$expected = hash_hmac('sha256', $signed, $secret);
$signature = $_SERVER['HTTP_X_OMER_SIGNATURE'] ?? '';
if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit;
}
$event = $method === 'GET' ? $_GET : json_decode($raw, true);
// Implement this function using a DATABASE TRANSACTION:
// 1. INSERT event.trans_id with a UNIQUE constraint; duplicate = return success.
// 2. Validate user_id, status and the non-negative integer amount_local.
// 3. status=1: credit amount_local; status=2: debit amount_local.
//    Link a reversal using original_trans_id; allow it to arrive before the credit.
// 4. test=1: use a TEST ledger, not real balances. Never infer mode from the ID.
// 5. Commit the ledger change and the event together; failures return HTTP 500.
// Return 2xx only after durable processing. Never credit from a browser redirect.
process_omer_event_atomically($event); // Your own persistence implementation.
http_response_code(200);
echo 'OK';

import { createHmac, timingSafeEqual } from "node:crypto";

// GET: signed = configuredPublicOrigin + req.originalUrl (exact raw path + query).
// POST: signed = raw request body bytes, before JSON parsing.
export function verify(signed, header, secret) {
  if (!secret || typeof header !== "string") return false;
  const expected = createHmac("sha256", secret).update(signed).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(header ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Process a callback reliably

Keep signature verification, event validation and durable processing on your server. A successful HTTP response tells us you have safely accepted this event.

1. Verify before trusting fields

   Use the App secret and the configured public origin, not an untrusted Host header. Behind a reverse proxy, preserve the exact raw request path and query.

2. Validate the identity and event

   Check user_id against your users; allow the documented type and status values. Treat all query values as strings until validated. Preserve the full trans_id, including cpx:, prime: and reversal suffixes.

3. Separate test and live processing

   test=1 belongs only in your test ledger. test=0 is live. Do not infer the mode from the transaction ID prefix.

4. Commit once in a database transaction

   Use a unique event key and commit the event record and ledger update atomically. For a duplicate already committed event, make no change and return 2xx. A reversal has its own trans_id and references the credit through original_trans_id.

5. Acknowledge after durable acceptance

   Return 200 OK after committing, or after storing the event in a durable queue you will process reliably. A memory-only task is not enough. Return 5xx for a temporary failure. Respond within 15 seconds.

Retries & idempotency

The first delivery is immediate. Network failures, 408, 429 and 5xx are retried at the intervals below. Other 3xx and 4xx stop automatic retries; redirects are not followed. After fixing the endpoint, contact support with the transaction ID to arrange a replay.

Delivery may repeat after a timeout or recovery, even if your first processing succeeded. Keep a unique key on App + test mode + full trans_id, and return 2xx for an already committed event without applying it again.

Testing

Use Send test postback to verify your receiving endpoint: these events have test-* IDs. Allowlisted users can also test the wall while the app is in test mode; those callbacks keep provider-prefixed IDs. Always isolate events using test=1, not the ID prefix. Test callbacks must never change real balances. Passing the send test does not validate the upstream API, real survey completion or return redirect.

In App → Postback settings, enter a user ID that exists in your test system. Start with the main callback, record the returned transId, then test the other types. The button saves the visible callback settings before sending and calls your real URL.

Request launch

• Your main URL is saved, reachable and verifies the HMAC header.
• All event types, duplicate handling, reversal handling and test isolation have passed your checks.
• Your iframe uses stable user IDs and server-generated links; you have checked your supported browsers.
• Save every edited tab, then click Request launch. Keep the saved configuration unchanged while it is being reviewed.

Saving changes while a request is pending withdraws that request; finish editing and submit again. Account approval does not automatically publish Apps. After approval, start a fresh wall session and verify live callbacks before gradually increasing traffic.

Troubleshooting

When contacting support, include App code, full trans_id if available, UTC time, HTTP status and a redacted error message. Never send App secret, security hash or live user credentials.