Quest evidence
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 type | You 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.