Your First Webhook

npm install express

// server.js
import express from 'express';
import crypto from 'crypto';

const app = express();
const WEBHOOK_SECRET = process.env.ARCUS_WEBHOOK_SECRET;

// Use raw body for signature verification
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['arcus-signature'];

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

  // Verify the signature
  const [tPart, vPart] = signature.split(',');
  const timestamp = tPart.replace('t=', '');
  const receivedSig = vPart.replace('v1=', '');

  const payload = `${timestamp}.${req.body.toString()}`;
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(receivedSig))) {
    return res.status(400).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  console.log(`Received event: ${event.type} (${event.id})`);
  console.log(JSON.stringify(event.data.object, null, 2));

  res.status(200).json({ received: true });
});

app.listen(4242, () => console.log('Listening on :4242'));

ARCUS_WEBHOOK_SECRET=whsec_test_placeholder node server.js

ngrok http 4242

curl -X POST https://api.arcuserp.com/v1/entities/$ARCUS_ENTITY_ID/webhook_endpoints \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://abc123.ngrok-free.app/webhook",
    "events": ["order.confirmed", "order.created"],
    "description": "Local dev webhook"
  }'

export ARCUS_WEBHOOK_SECRET=whsec_...

Received event: order.confirmed (evt_01H...)
{
  "id": "ord_01H...",
  "object": "order",
  "document_type": "sales_order",
  "status": "confirmed",
  ...
}

app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  // ... verify signature (same as above) ...

  const event = JSON.parse(req.body);

  // 1. Respond immediately -- don't block on processing
  res.status(200).json({ received: true });

  // 2. Deduplicate using event.id
  const alreadyProcessed = await db.webhookEvents.findUnique({ where: { id: event.id } });
  if (alreadyProcessed) return;

  await db.webhookEvents.create({ data: { id: event.id } });

  // 3. Process asynchronously
  await queue.enqueue({ type: event.type, data: event.data.object });
});