Agent Skills: Navan Webhooks & Events

Navan Webhooks & Events

Overview

Navan supports asynchronous event delivery via callback URLs registered through the REST API. Since there is no public SDK, webhook handlers receive raw HTTP POST requests with JSON payloads. This skill covers endpoint setup, payload verification, event routing, and idempotent processing for the key event types: booking lifecycle, expense workflow, and travel disruptions.

Prerequisites

• Active Navan account with API credentials (Admin > Travel admin > Settings > Integrations)
• OAuth 2.0 access token (see navan-install-auth)
• Publicly accessible HTTPS endpoint for callback URL (use ngrok for local development)
• Node.js 18+ with Express or equivalent HTTP framework

Instructions

Step 1: Register a Webhook Callback URL

const response = await fetch('https://api.navan.com/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://your-domain.com/webhooks/navan',
    events: [
      'booking.created',
      'booking.updated',
      'booking.cancelled',
      'expense.submitted',
      'expense.approved',
      'expense.rejected',
      'trip.disrupted'
    ],
    secret: process.env.NAVAN_WEBHOOK_SECRET
  })
});
const webhook = await response.json();
console.log('Webhook registered:', webhook.id);

Step 2: Verify Payload Signatures

import crypto from 'node:crypto';

function verifySignature(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Step 3: Build the Webhook Handler

import express from 'express';
const app = express();

// Track processed events for idempotency
const processedEvents = new Set<string>();

app.post('/webhooks/navan', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['x-navan-signature'] as string;
  const rawBody = req.body.toString();

  // Verify authenticity
  if (!verifySignature(rawBody, signature, process.env.NAVAN_WEBHOOK_SECRET!)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Acknowledge immediately — process async
  res.status(200).json({ received: true });

  const event = JSON.parse(rawBody);

  // Idempotency check — Navan may retry on timeout
  if (processedEvents.has(event.id)) return;
  processedEvents.add(event.id);

  // Route by event type
  switch (event.type) {
    case 'booking.created':
      await handleNewBooking(event.data);
      break;
    case 'expense.submitted':
      await handleExpenseSubmission(event.data);
      break;
    case 'trip.disrupted':
      await handleDisruption(event.data);
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }
});

Step 4: Handle Key Event Types

async function handleNewBooking(data: {
  booking_id: string;
  traveler_email: string;
  trip_type: 'flight' | 'hotel' | 'car';
  total_cost: number;
  currency: string;
}) {
  // Notify travel manager, update internal systems
  console.log(`New ${data.trip_type} booking: ${data.booking_id} — $${data.total_cost}`);
}

async function handleExpenseSubmission(data: {
  expense_id: string;
  submitter_email: string;
  amount: number;
  category: string;
}) {
  // Route to approval workflow
  console.log(`Expense submitted: ${data.expense_id} — $${data.amount} (${data.category})`);
}

async function handleDisruption(data: {
  trip_id: string;
  disruption_type: 'cancellation' | 'delay' | 'gate_change';
  severity: 'low' | 'medium' | 'high';
  affected_travelers: string[];
}) {
  // Trigger alerts for high-severity disruptions
  if (data.severity === 'high') {
    console.log(`ALERT: ${data.disruption_type} affecting ${data.affected_travelers.length} travelers`);
  }
}

Output

A running webhook endpoint that receives real-time Navan events, verifies payload authenticity, deduplicates retries, and routes events to typed handler functions. The handler acknowledges receipt immediately (HTTP 200) and processes events asynchronously to avoid timeout-triggered retries.

Error Handling

| Error | Code | Solution | |-------|------|----------| | Invalid signature | 401 | Verify NAVAN_WEBHOOK_SECRET matches the secret used during registration | | Endpoint unreachable | N/A | Ensure HTTPS is valid and publicly accessible; check firewall rules | | Duplicate events | N/A | Implement idempotency using event ID tracking (Set, Redis, or database) | | Payload timeout | 408 | Respond with 200 before processing; handle work asynchronously | | Webhook disabled | 410 | Re-register the callback URL; Navan disables after repeated failures |

Examples

List registered webhooks:

curl -s -H "Authorization: Bearer $NAVAN_ACCESS_TOKEN" \
  https://api.navan.com/v1/webhooks | python3 -m json.tool

Delete a webhook:

curl -s -X DELETE \
  -H "Authorization: Bearer $NAVAN_ACCESS_TOKEN" \
  https://api.navan.com/v1/webhooks/WEBHOOK_ID

Test with ngrok for local development:

ngrok http 3000
# Use the HTTPS URL as your callback URL when registering

Resources

• Navan Help Center — Official documentation and support
• Navan Integrations — Available integration partners and setup guides
• Navan Security — Compliance certifications and data handling policies

Next Steps

After setting up webhooks, see navan-rate-limits to add throttling to your event processing pipeline, or navan-security-basics for credential rotation and SSO hardening.