Offer Completed Webhook — Encore Notifies Your Server

POST /webhooks/encore HTTP/1.1
Content-Type: application/json
X-Webhook-Signature: 5a4f2e8c1b3d9e7f6a0c8b2d4e6f1a3c5b7d9e0f...
X-Webhook-Timestamp: 1772044200

{
  "event": "offer_completed",
  "timestamp": "2026-02-25T18:30:00.000Z",
  "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "userId": "usr_9f8e7d6c-5b4a-3210-fedc-ba0987654321",
  "campaignName": "Audible Premium Plus",
  "payout": 10
}

<X-Webhook-Timestamp>.<raw_body>

import express from 'express';
import crypto from 'node:crypto';

const app = express();
const MAX_SKEW_SECONDS = 300; // 5 minutes

// Fail fast at boot rather than inside createHmac on the first delivery.
const SIGNING_SECRET = process.env.ENCORE_WEBHOOK_SECRET; // whsec_...
if (!SIGNING_SECRET) {
  throw new Error(
    'ENCORE_WEBHOOK_SECRET is not set — copy the signing secret from the dashboard under Settings.',
  );
}

// Mount the RAW body parser on this route — the signature covers exact bytes.
app.post(
  '/webhooks/encore',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.get('X-Webhook-Signature');
    const timestamp = req.get('X-Webhook-Timestamp');
    const rawBody = req.body.toString('utf8');

    if (!signature || !timestamp) {
      return res.status(400).send('Missing signature headers');
    }

    // 1. Replay protection: reject stale (or future-dated) timestamps.
    const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
    if (!Number.isFinite(age) || age > MAX_SKEW_SECONDS) {
      return res.status(401).send('Timestamp outside tolerance');
    }

    // 2. Recompute the HMAC over `${timestamp}.${rawBody}`.
    const expected = crypto
      .createHmac('sha256', SIGNING_SECRET)
      .update(`${timestamp}.${rawBody}`)
      .digest('hex');

    // 3. Constant-time compare — never `===`, which leaks timing information.
    const a = Buffer.from(signature, 'utf8');
    const b = Buffer.from(expected, 'utf8');
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).send('Invalid signature');
    }

    // 4. Verified. Acknowledge FIRST, then work asynchronously — there are no retries,
    //    so a slow handler risks the 5s timeout even though we already have the event.
    res.status(200).send('OK');

    const payload = JSON.parse(rawBody);
    if (payload.event === 'offer_completed') {
      // Idempotent on transactionId — see "Handle duplicates idempotently".
      void grantReward({
        transactionId: payload.transactionId,
        userId: payload.userId,
        campaignName: payload.campaignName,
        payout: payload.payout, // may be null
      });
    }
  },
);

app.listen(3000);