Skip to main content
Version: 3.x

Redirect URLs

When a participant leaves a survey — complete, disqualification, or any other outcome — TapResearch sends them to your redirect URL with signed parameters.

Set it in the Publisher Dashboard under your app's Settings tab → App title settings → Redirect URL. The URL must start with https://, and you must run Test redirect URL successfully before you can save it.

The redirect URL can be handled in two ways:

  1. Placeholder substitution (recommended for full control)
  2. Query parameter appending (automatic fallback)

In both cases, a SHA-256 HMAC signature (sech) is added to verify integrity.

Parameters​

NameDescription
statusWhy the participant returned. See Redirect statuses.
revenueYour revenue in USD, formatted as a float (e.g. 0.45, 0.0).
rewardParticipant reward in your currency, formatted as a float (e.g. 50.0).
tidTapResearch's match ID for the survey attempt — the same value as cpid in the reward postback. Blank for session and pre-match statuses.
click_idTapResearch's identifier for the participant's session.
pass_throughYour pass-through values, re-encoded as URL-safe Base64 JSON. Empty if you didn't send any.
sechSHA-256 HMAC signature verifying the signed parameters.

Redirect modes​

Placeholder substitution​

If your redirect URL contains placeholders using curly braces (e.g., {STATUS}), those placeholders will be replaced before redirecting.

Supported placeholders:

  • {STATUS}
  • {REVENUE}
  • {REWARD}
  • {TID}
  • {CLICK_ID}
  • {PASS_THROUGH}

Use matching lowercase query parameter names, such as status={STATUS}, so the values are signed correctly.

Example:

https://example.com/survey-complete?status={STATUS}&tid={TID}&pass_through={PASS_THROUGH}

After substitution:

https://example.com/survey-complete?status=1&tid=8f14e45fceea167a5a36dedd4bea2543&pass_through=eyJzZXNzaW9uX2lkIjoiYWJjMTIzIn0%3D&sech=779994bae03770c278f011862e843203ef1db97f1a7a0104cd6f80a951b79395

Only the parameters represented by placeholders are signed.

Query parameter appending (no placeholders)​

If your redirect URL does not contain placeholders, the system automatically appends all parameters:

  • status
  • revenue
  • reward
  • tid
  • click_id
  • pass_through

Example base URL:

https://example.com/survey-complete

Result:

https://example.com/survey-complete?status=1&revenue=0.45&reward=50.0&tid=8f14e45fceea167a5a36dedd4bea2543&click_id=c9f0f895fb98ab9159f51fd0297e236d&pass_through=eyJzZXNzaW9uX2lkIjoiYWJjMTIzIn0%3D&sech=007643e79eff5c8bbb68bbcbbff1f6465325d9570b8349607cac12d617a5813b

In this mode, all parameters are always signed.

How signing works​

The system computes a SHA-256 HMAC using your API secret.

Signing order​

Canonical signing order:

status,revenue,reward,tid,click_id,pass_through

Data string construction​

The signature is created by:

  1. Taking only the signed keys (depending on redirect mode).
  2. Ordering them according to the canonical signing order above.
  3. Joining their URL-decoded values with commas, exactly as they appear in the redirect.

Example (the appended redirect above):

1,0.45,50.0,8f14e45fceea167a5a36dedd4bea2543,c9f0f895fb98ab9159f51fd0297e236d,eyJzZXNzaW9uX2lkIjoiYWJjMTIzIn0=

Keep blank values as empty strings when joining the signed values.

Signature generation​

HMAC-SHA256(data_string, api_secret)

The resulting lowercase hex digest becomes the sech parameter.

How to validate the redirect​

When you receive the redirect:

  1. Extract the signed parameters that are present (status, revenue, reward, tid, click_id, pass_through).
  2. Join their URL-decoded string values with commas in the canonical order.
  3. Compute the SHA-256 HMAC using your API secret.
  4. Compare your result to the received sech.
require "openssl"
require "uri"

api_secret = "26dcc0fc7b6208fdfeffaf19f627cb4a" # example secret
url = "https://example.com/survey-complete?status=1&revenue=0.45&reward=50.0&tid=8f14e45fceea167a5a36dedd4bea2543&click_id=c9f0f895fb98ab9159f51fd0297e236d&pass_through=eyJzZXNzaW9uX2lkIjoiYWJjMTIzIn0%3D&sech=007643e79eff5c8bbb68bbcbbff1f6465325d9570b8349607cac12d617a5813b"

params = URI.decode_www_form(URI(url).query).to_h
signed_keys = %w[status revenue reward tid click_id pass_through]
data = signed_keys.select { |key| params.key?(key) }.map { |key| params[key] }.join(",")
expected = OpenSSL::HMAC.hexdigest("SHA256", api_secret, data)

puts expected == params["sech"] # => true

If they do not match:

  • The parameters were modified, or
  • The wrong API secret was used.

See Redirect statuses for what each status value means.