# Webhook events

> Headers, signatures, retries and the payload of each event AdQuest sends to your endpoint.

Source: https://dashboard.adquest.io/docs/api/webhook-events · Audience: Developers · Section: API reference

## The request

AdQuest sends a POST with a JSON body to your HTTPS endpoint. Answer with any 2xx status within 10 seconds.

| Header | Value |
| --- | --- |
| X-AdQuest-Event | The event type, such as quest.completed. |
| X-AdQuest-Event-Id | A stable ID for this event. Use it to ignore duplicates. |
| X-AdQuest-Timestamp | Unix time when this attempt was sent. |
| X-AdQuest-Signature | sha256= and the hex HMAC-SHA256 of the raw body. |
| X-AdQuest-Signature-V2 | t=<unix>,v1=<hex>. The HMAC covers the timestamp and the body, so you can reject old requests. |
| X-AdQuest-Signature-V2-Previous | Only for 24 hours after you replace the signing secret: the same signature made with the old secret. Accept a request when either header matches the secret you hold. |

## Verify the timestamped signature

Prefer X-AdQuest-Signature-V2. It signs the string timestamp.body with your webhook signing secret. Reject a request whose timestamp is more than 5 minutes old.

**Node.js**

```typescript
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhookV2(rawBody: string, header: string, secret: string, toleranceSeconds = 300) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header);
  if (!match) return false;
  if (Math.abs(Date.now() / 1000 - Number(match[1])) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(match[1] + "." + rawBody).digest("hex");
  return timingSafeEqual(Buffer.from(match[2]), Buffer.from(expected));
}
```

- [Webhooks guide](https://dashboard.adquest.io/docs/webhooks): Registering an endpoint and handling retries.

## Retries

- A delivery that does not get a 2xx is retried, up to 8 attempts in all.
- The wait grows between attempts: 1 minute, 5 minutes, 30 minutes, 2 hours, then 12 hours.
- After the last attempt the delivery is marked dead. The publisher can replay it from the delivery history in the dashboard.
- When a delivery goes dead, the platform owner gets one in-app notice, Webhooks are not reaching your server, that links to the platform’s Connection tab. More dead deliveries refresh that notice while it is unseen. A dead fulfillment event raises Rewards are not reaching your server instead.
- A retried delivery keeps the same X-AdQuest-Event-Id.

## Events AdQuest sends

| Event | When |
| --- | --- |
| quest.completed | A participant’s quest completion is settled. |
| lottery.winner | A participant wins a lottery prize. |
| fulfillment.requested | A reward must be delivered by you. HTTPS endpoints only. |
| fulfillment.rejected | You rejected a fulfillment. Sent only to endpoints subscribed to every event (*). HTTPS endpoints only. |

> **Subscribing.** A webhook subscribes to quest.completed, lottery.winner, fulfillment.requested, or * for every event. Any other event name is rejected when you save it. Only * also receives fulfillment.rejected.

## quest.completed

**Payload**

```json
{
  "quest_id": 23,
  "platform_id": 7,
  "platform_user_id": 55,
  "external_user_id": "player-42",
  "tokens": 10,
  "completed_at": "2026-01-01T12:00:00+00:00"
}
```

tokens is the participant’s share of AdQuest tokens. On a quest whose reward you deliver yourself (White Label), tokens is 0 and the reward comes in fulfillment.requested. The Event-Id is quest.completed:{completion id}.

## lottery.winner

**Payload**

```json
{
  "lottery_id": 4,
  "claim_id": 91,
  "external_user_id": "player-42",
  "ticket_number": "1G2736",
  "award_name": "Gift card",
  "claim_expires_at": "2026-02-01T00:00:00+00:00"
}
```

The payload has no email or phone. To send the winner’s email, post it to the winner contact route.

- [Post a winner’s contact](https://dashboard.adquest.io/docs/api/server-routes#winner-contact): POST /platform/lottery-claims/{claim}/contact

## fulfillment.requested

**Payload for a quest reward**

```json
{
  "quest_id": 23,
  "completion_id": 301,
  "external_user_id": "player-42",
  "occurred_at": "2026-01-01T12:00:00+00:00",
  "fulfillment_id": 12,
  "idempotency_key": "fulfillment:...",
  "amount": 10,
  "asset": "ADQ_TOKEN",
  "kind": "quest_reward"
}
```

**Payload for a lottery prize**

```json
{
  "lottery_id": 4,
  "claim_id": 91,
  "award_detail_id": 17,
  "occurred_at": "2026-01-01T12:00:00+00:00",
  "fulfillment_id": 13,
  "idempotency_key": "fulfillment:lottery_claim:91",
  "amount": 1,
  "asset": "PRIZE",
  "kind": "lottery_prize"
}
```

Deliver the reward, then acknowledge it with your own reference, or reject it with a reason code if your review refuses it. Both answers are final; repeating the same one is safe.

- [Acknowledge a fulfillment](https://dashboard.adquest.io/docs/api/server-routes#server-acknowledge-fulfillment): POST /server/fulfillments/{id}/acknowledge
- [Reject a fulfillment](https://dashboard.adquest.io/docs/api/server-routes#server-reject-fulfillment): POST /server/fulfillments/{id}/reject

## fulfillment.rejected

**Payload**

```json
{
  "fulfillment_id": 12,
  "kind": "quest_reward",
  "reason_code": "account_closed",
  "amount": 10,
  "asset": "ADQ_TOKEN"
}
```

An echo of your own reject call. Nothing returns to the quest’s budget. The Event-Id is fulfillment.rejected:{fulfillment id}.
