Webhooks
Receive signed server notifications and reconcile outcomes in your own backend.
On this page
Prerequisites
- A public HTTPS endpoint on your backend that can read the raw request body.
- The publisher, who adds your endpoint in the dashboard. The dashboard calls webhooks reward notices.
Register your endpoint
Build the endpoint. It receives a POST with a JSON body and must answer 2xx within 10 seconds.
Ask the publisher to add its URL as a webhook on the platform, with the events you need. Send test notices only gives you sandbox deliveries.
Save the signing secret that is shown once. It is separate from the Secret Key.
Use the delivery history to see response codes and failures, and replay a delivery after you fix your receiver.
Choose your events
You can subscribe to quest.completed, lottery.winner and fulfillment.requested, or to * for every event. Subscribe only to the ones you handle. fulfillment.requested needs an HTTPS endpoint: deliver the reward, then acknowledge or reject it from your server. fulfillment.rejected, sent after a fulfillment is rejected, reaches only HTTPS endpoints subscribed to *.
Verify before processing
Verify the signature on the exact raw body before you parse it. Prefer the timestamped X-AdQuest-Signature-V2, which also lets you reject old requests. The older X-AdQuest-Signature is sha256= and the hex HMAC-SHA256 of the raw body.
import { createHmac, timingSafeEqual } from "node:crypto";
// header is X-AdQuest-Signature-V2: t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.rawBody">
export function verifyWebhook(rawBody: string, header: string, secret: string) {
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(match[2]), Buffer.from(expected));
}
// rawBody = await request.text(); // Before JSON parsing.
// header = request.headers.get("X-AdQuest-Signature-V2") ?? "";
// On failed verification: return 401 and do not process the payload.Handle retries and reconciliation
- Use X-AdQuest-Event for the event type and X-AdQuest-Event-Id to ignore duplicates. Apply the event and record its ID in one step.
- Return 2xx after you have safely stored the event. Queue slow work and expect duplicate or late deliveries.
- A failed delivery is retried with a growing wait, up to 8 attempts in total. After that it is dead and can be replayed from the dashboard, and the platform owner gets the in-app notice Webhooks are not reaching your server.
- Check the payload before you grant anything in your own app.
- Keep tokens, signing secrets and personal data out of your logs.