Payload Structure

POST /webhooks/fieldnation HTTP/1.1
Host: your-endpoint.com
Content-Type: application/json
X-FN-Signature: sha256=bba5b9134ae2fdd020c2b55ab93a113a...
X-FN-Webhook-Id: 892d08af-23bc-44e0-bafa-fac1cc88b559
X-FN-Delivery-Id: 66b2c434-519e-4b3f-be20-00216b600873:1
X-FN-Event-Trace-Id: be107c0c-5095-4d74-aa25-45e450777869
X-FN-Request-Timestamp: 1768920958434

{
  "event": {
    "name": "workorder.status.published",
    "params": {
      "status_id": 2,
      "work_order_id": 12345
    }
  },
  "timestamp": "2026-01-20T08:55:58-06:00",
  "triggered_by_user": {
    "id": 1068
  },
  "workorder": {
    "id": 12345,
    "title": "Router Installation - Site 42"
  }
}

{
  "webhookAttribute": {
    "header": {
      "Authorization": "Bearer your-api-token",
      "X-Custom-ID": "your-identifier"
    }
  }
}

{
  "event": {
    "name": "workorder.status.published",
    "params": {
      "status_id": 2,
      "work_order_id": 12345
    }
  },
  "timestamp": "2026-01-20T08:55:58-06:00",
  "triggered_by_user": {
    "id": 1068
  },
  "workorder": {
    "id": 12345,
    "title": "Router Installation - Site 42"
  }
}

{
  "status_id": 2,
  "work_order_id": 12345
}

{
  "eta": {
    "start": {
      "utc": "2026-01-20 14:00:00",
      "local": { "date": "2026-01-20", "time": "09:00:00" }
    },
    "end": {
      "utc": "2026-01-20 18:00:00",
      "local": { "date": "2026-01-20", "time": "13:00:00" }
    },
    "hour_estimate": 4,
    "status": {
      "name": "confirmed",
      "updated": {
        "utc": "2026-01-19 20:00:00",
        "local": { "date": "2026-01-19", "time": "15:00:00" }
      }
    },
    "mode": "exact"
  }
}

curl -X GET "https://api.fieldnation.com/api/rest/v2/workorders/12345" \
  -H "Authorization: Bearer ${FN_ACCESS_TOKEN}" \
  -H "Accept: application/json"

const express = require('express');
const crypto = require('crypto');
const app = express();

// Use raw body for signature verification
app.use(express.raw({ type: 'application/json' }));

app.post('/webhooks/fieldnation', async (req, res) => {
  try {
    // 1. Verify signature
    const signature = req.headers['x-fn-signature'];
    const secret = process.env.WEBHOOK_SECRET;

    if (!verifySignature(req.body, signature, secret)) {
      return res.status(401).send('Invalid signature');
    }

    // 2. Parse payload
    const payload = JSON.parse(req.body.toString());
    const {
      event,
      timestamp,
      triggered_by_user,
      workorder
    } = payload;

    // 3. Get delivery ID for idempotency (from headers)
    const deliveryId = req.headers['x-fn-delivery-id'];

    if (await hasProcessedEvent(deliveryId)) {
      console.log(`Duplicate event: ${deliveryId}`);
      return res.status(200).send('Already processed');
    }

    // 4. Respond immediately (< 5 seconds)
    res.status(200).send('OK');

    // 5. Process asynchronously
    await processEventAsync({
      eventName: event.name,
      eventParams: event.params,
      deliveryId,
      timestamp,
      triggeredByUser: triggered_by_user,
      workorder
    });

  } catch (error) {
    console.error('Webhook processing error:', error);
    res.status(500).send('Internal error');
  }
});

function verifySignature(rawBody, signature, secret) {
  if (!signature) return false;

  const [algorithm, hash] = signature.split('=');
  const expectedHash = crypto
    .createHmac(algorithm, secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expectedHash),
    Buffer.from(hash)
  );
}

async function hasProcessedEvent(eventId) {
  // Check your database or cache
  return await redis.exists(`event:${eventId}`);
}

async function processEventAsync(event) {
  // Mark as processing
  await redis.setex(`event:${event.deliveryId}`, 86400, 'processed');

  // Handle based on event type
  switch (event.eventName) {
    case 'workorder.status.published':
      await syncToSalesforce(event.workorder);
      await notifyProviders(event.workorder);
      break;

    case 'workorder.status.assigned':
      await updateDispatchBoard(event.workorder);
      await notifyTechnician(event.workorder);
      break;

    case 'workorder.status.work_done':
      await triggerApprovalFlow(event.workorder);
      break;

    case 'workorder.status.approved':
      await generateInvoice(event.workorder);
      await updateAccounting(event.workorder);
      break;
  }
}

app.listen(3000);

// Redis example
async function processWebhook(req, payload) {
  const deliveryId = req.headers['x-fn-delivery-id'];
  const key = `webhook:${deliveryId}`;

  // Try to set key with NX (only if not exists)
  const wasSet = await redis.set(key, '1', 'EX', 86400, 'NX');

  if (!wasSet) {
    console.log('Duplicate webhook, skipping');
    return;
  }

  // Process the webhook
  await handleEvent(payload);
}

CREATE TABLE processed_webhooks (
  event_id VARCHAR(255) PRIMARY KEY,
  processed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  event_name VARCHAR(255),
  work_order_id INTEGER
);

CREATE INDEX idx_processed_at ON processed_webhooks(processed_at);

async function hasProcessedEvent(eventId) {
  const result = await db.query(
    'SELECT event_id FROM processed_webhooks WHERE event_id = $1',
    [eventId]
  );
  return result.rows.length > 0;
}

async function markEventProcessed(eventId, eventName, workOrderId) {
  await db.query(
    'INSERT INTO processed_webhooks (event_id, event_name, work_order_id) VALUES ($1, $2, $3) ON CONFLICT DO NOTHING',
    [eventId, eventName, workOrderId]
  );
}

HTTP/1.1 200 OK
Content-Type: text/plain

OK

async function enrichWorkOrder(workOrderId) {
  const response = await fetch(
    `https://api.fieldnation.com/api/rest/v2/workorder/${workOrderId}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );

  return await response.json();
}

curl -X GET https://api-sandbox.fndev.net/api/v1/webhooks/delivery-logs/del_xyz789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

app.post('/webhooks', async (req, res) => {
  // Verify first
  if (!verifySignature(req.body, req.headers['x-fn-signature'], secret)) {
    return res.status(401).send('Invalid signature');
  }

  // Parse once
  const payload = JSON.parse(req.body.toString());

  // Validate required fields
  if (!payload.eventId || !payload.eventName || !payload.data) {
    return res.status(400).send('Invalid payload');
  }

  // Continue processing...
});

const provider = data.provider || null;
const providerName = provider?.name || 'Unassigned';
const tags = data.tags || [];
const customFields = data.customFields || {};

if (process.env.NODE_ENV === 'development') {
  console.log('Raw webhook payload:', JSON.stringify(payload, null, 2));
}