# Webhooks

> Receive signed server notifications and reconcile outcomes in your own backend.

Source: https://dashboard.adquest.io/docs/webhooks · Audience: Developers · Section: Build

## 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. Build the endpoint. It receives a POST with a JSON body and must answer 2xx within 10 seconds.
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. Save the signing secret that is shown once. It is separate from the Secret Key.
4. Use the delivery history to see response codes and failures, and replay a delivery after you fix your receiver.

- [Publisher guide: reward notices](https://dashboard.adquest.io/docs/dashboard/keys#reward-notices): Send this page to the publisher.

## 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 *.

- [Webhook events](https://dashboard.adquest.io/docs/api/webhook-events): Headers, signatures, retries and each payload, fulfillment.rejected included.
- [Answer payouts](https://dashboard.adquest.io/docs/quest-evidence/activities#payouts): Acknowledge or reject a fulfillment.

## 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.

**Node.js signature helper**

```typescript
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.

- [Get help with a delivery](https://dashboard.adquest.io/support): Include event IDs and response codes, never secrets.

## Next steps

- [Webhook events](https://dashboard.adquest.io/docs/api/webhook-events): Every header and payload.
- [Test & go live](https://dashboard.adquest.io/docs/launch): Verify signatures, deduplication and replays.
- [Troubleshooting](https://dashboard.adquest.io/docs/troubleshooting): Find the next action for a failed delivery.
