Webhooks

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#

1. 1

   Build the endpoint. It receives a POST with a JSON body and must answer 2xx within 10 seconds.

2. 2

   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.

3. 3

   Save the signing secret that is shown once. It is separate from the Secret Key.

4. 4

   Use the delivery history to see response codes and failures, and replay a delivery after you fix your receiver.

Choose your events#

AdQuest sends three events: quest.completed, lottery.winner and fulfillment.requested. Subscribe only to the ones you handle. fulfillment.requested needs an HTTPS endpoint.

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";

export function verifyWebhook(rawBody: string, signature: string, secret: string) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const receivedBytes = Buffer.from(signature);
  const expectedBytes = Buffer.from(expected);
  return receivedBytes.length === expectedBytes.length &&
    timingSafeEqual(receivedBytes, expectedBytes);
}
// rawBody = await request.text(); // Before JSON parsing.
// signature = request.headers.get("X-AdQuest-Signature") ?? "";
// 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 up to 8 times with a growing wait. After that it is dead and can be replayed from the dashboard.
• Check the payload before you grant anything in your own app.
• Keep tokens, signing secrets and personal data out of your logs.

Next steps#