Skip to documentation
AdQuestDocs

Custom evidence

API type: custom. Own-platform only. Prove an outcome with a URL your server answers, or with a manual review.

On this page

What you do

Evidence typeYou build
URL callback (url_callback)An HTTPS endpoint that answers AdQuest’s signed check with { "verified": true } when the user qualifies.
Manual review (manual_review)Nothing on your server. The participant submits evidence and a reviewer approves or rejects it.

URL callback

When the participant asks to complete, AdQuest POSTs { quest_id, platform_id, external_user_id } to your URL. Check X-AdQuest-Signature-V2: t=<unix seconds>,v1=<hex HMAC-SHA256 of t + "." + raw body> with your Event signing secret, and refuse a t more than 5 minutes off. X-AdQuest-Event-Id is the same for every check of one participant and quest. Look the user up in your own data and answer 2xx with verified: true only when they qualify, otherwise verified: false.

Check the signature (Node.js)
import { createHmac, timingSafeEqual } from "node:crypto";

export function isFromAdQuest(rawBody: string, header: string, secret: string): boolean {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header);
  if (!match || Math.abs(Date.now() / 1000 - Number(match[1])) > 300) return false;
  const expected = createHmac("sha256", secret).update(match[1] + "." + rawBody).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(match[2]));
}
Your answer
{ "verified": true }
Ask to complete — using questRequest from the Quest evidence overview
const completion = await questRequest(config, questId, "complete", { evidence_type: "url_callback" });
  • The check does not follow redirects, waits 2 seconds to connect and 4 seconds in total, and reads at most 8 KB.
  • It is a question, not a command: do not grant or change anything when it arrives.

Manual review

Submit evidence for review
const result = await questRequest(config, questId, "complete", {
  evidence_type: "manual_review",
  evidence: participantEvidence,
});
// completed: false and custom.status: pending until a reviewer decides.
const status = await client.getCustomStatus(questId);

Approval settles the quest. After a rejection the participant can submit new evidence.

Check before publishing

  • For a callback: a user who qualifies completes, one who does not is refused, and a request with a wrong signature gets no answer from you.
  • For a review: test a pending, an approved and a rejected submission, and show the rejection reason.

Next steps

Something unclear, missing or wrong here? Tell us