Extension Events

{
  "id":          "evt_01HZX...",
  "type":        "order.created",
  "version":     "1",
  "workspaceId": "6659b411-9cd7-40ac-9a73-1e7801d89f55",
  "environmentId": "8a5f2d1e-3d2a-4d24-93a1-fd3f9e1f37f0",
  "createdAt":   "2026-05-31T10:00:00.000Z",
  "data": {
    "orderId":   "ord_01HZX...",
    "cartId":    "cart_01HZX...",
    "status":    "pending",
    "currency":  "USD",
    "total":     12900
  }
}

// Node.js — import from the subpath entry (uses node:crypto)
import { verifyWebhook } from '@usethrottle/extension-bridge/webhook';
// Express / Fastify / plain Node
app.post('/webhooks/throttle', express.raw({ type: '*/*' }), (req, res) => {
  const rawBody = req.body.toString('utf8');   // ← raw string, BEFORE JSON.parse
  const signature = req.headers['x-throttle-signature'] as string;
  const secret = process.env.EXTENSION_WEBHOOK_SECRET!; // from install response
  const valid = verifyWebhook(rawBody, signature, secret);
  if (!valid) {
    return res.status(400).json({ error: 'Invalid signature' });
  }
  const event = JSON.parse(rawBody);
  console.log('Received event:', event.id, event.type);
  res.status(200).send();
});

// Cloudflare Workers / Deno / Bun — use verify.ts (Web Crypto API, async)
import { verifyWebhook } from '@usethrottle/extension-bridge/verify';
export default {
  async fetch(request: Request): Promise<Response> {
    const rawBody = await request.text();
    const signature = request.headers.get('x-throttle-signature') ?? '';
    const secret = env.EXTENSION_WEBHOOK_SECRET;
    const valid = await verifyWebhook(rawBody, signature, secret);
    if (!valid) return new Response('Bad signature', { status: 400 });
    const event = JSON.parse(rawBody);
    // handle event
    return new Response('ok');
  },
};

// Store event IDs before processing side effects to handle at-least-once delivery.
// Example with a database:
const eventId = event.id;
const alreadyProcessed = await db.query(
  'SELECT 1 FROM processed_events WHERE event_id = $1',
  [eventId],
);
if (alreadyProcessed.rowCount > 0) {
  return res.status(200).json({ status: 'duplicate' });
}
// Process the event (idempotent side effects here)
await processOrder(event.data);
// Mark as processed
await db.query(
  'INSERT INTO processed_events (event_id, event_type, processed_at) VALUES ($1, $2, NOW())',
  [eventId, event.type],
);

# Inspect deliveries for an installation
GET /api/v1/installations/:id/deliveries?limit=50&offset=0
# Replay a dead-lettered delivery
POST /api/v1/installations/:id/deliveries/:deliveryId/replay
# Send a verification ping to the installation's webhook URL
POST /api/v1/installations/:id/test