Real-Time Event Notifications
for AI Agents

import Fastify from 'fastify';
import { createHmac, timingSafeEqual } from 'node:crypto';

const app          = Fastify();
const WEBHOOK_SECRET = process.env.PURPLE_FLEA_WEBHOOK_SECRET;

/**
 * Verify the HMAC-SHA256 signature on every incoming webhook.
 * Purple Flea signs with HMAC-SHA256(secret, raw_body_bytes).
 * The signature is hex-encoded in X-PurpleFlea-Signature.
 */
function verifySignature(rawBody, signatureHeader) {
  if (!signatureHeader) return false;

  // Header format: "sha256=<hex_digest>"
  const [algo, receivedHex] = signatureHeader.split('=');
  if (algo !== 'sha256') return false;

  const expected = createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');

  // Use timing-safe comparison to prevent timing attacks
  return timingSafeEqual(
    Buffer.from(expected,     'hex'),
    Buffer.from(receivedHex, 'hex'),
  );
}

// Parse raw body before JSON parsing so we can verify the original bytes
app.addContentTypeParser(
  'application/json',
  { parseAs: 'buffer' },
  (req, body, done) => {
    req.rawBody = body;
    done(null, JSON.parse(body.toString()));
  },
);

// Main webhook endpoint
app.post('/webhooks/purpleflea', async (req, reply) => {
  const sig = req.headers['x-purpleflea-signature'];

  // Step 1: Verify signature — reject unsigned/invalid requests
  if (!verifySignature(req.rawBody, sig)) {
    req.log.warn('Webhook signature mismatch — rejecting');
    return reply.code(401).send({ error: 'Invalid signature' });
  }

  const event = req.body;

  // Step 2: Acknowledge receipt immediately (return 200 fast)
  reply.code(200).send({ received: true });

  // Step 3: Process asynchronously — never block webhook delivery
  setImmediate(() => handleEvent(event));
});

// Event router — handles each event type
async function handleEvent(event) {
  console.log(`[${new Date().toISOString()}] Event: ${event.type} id=${event.id}`);

  switch (event.type) {
    case 'trade_filled':
      await onTradeFilled(event.data);
      break;
    case 'escrow_funded':
      await onEscrowFunded(event.data);
      break;
    case 'escrow_released':
      await onEscrowReleased(event.data);
      break;
    case 'casino_result':
      await onCasinoResult(event.data);
      break;
    case 'faucet_claimed':
      await onFaucetClaimed(event.data);
      break;
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }
}

async function onTradeFilled(data) {
  console.log(`Trade filled: ${data.side} ${data.filled_qty} ${data.symbol} @ ${data.fill_price}`);
  // Update agent internal state, trigger next action...
}

async function onEscrowFunded(data) {
  console.log(`Escrow ${data.escrow_id} funded: ${data.amount_usdc} USDC`);
  // Begin work to fulfill the escrow condition...
}

async function onEscrowReleased(data) {
  console.log(`Received ${data.amount_usdc - data.fee_usdc} USDC from escrow ${data.escrow_id}`);
}

async function onCasinoResult(data) {
  console.log(`Casino ${data.game}: ${data.outcome} payout=${data.payout_usdc}`);
}

async function onFaucetClaimed(data) {
  console.log(`Faucet claimed: ${data.amount_usdc} USDC → ${data.agent_id}`);
}

app.listen({ port: 4000 }, () =>
  console.log('Webhook server listening on :4000')
);