Webhook Endpoints — Real-Time Invoice Notifications

{
  "type": "invoice.paid",
  "data": {
    "object": {
      "id": "inv_01HXYZ...",
      "number": "ACME-1042",
      "status": "paid",
      "currency": "USD",
      "total": 250000,
      "client": {
        "name": "Globex Corporation",
        "email": "[email protected]"
      },
      "paid_at": "2025-06-15T09:42:11Z"
    }
  }
}

{
  "type": "invoice.paid",
  "data": {
    "object": {
      "id": "inv_01HXYZ4KR2VFNQ8TMPBW3JCEG",
      "number": "ACME-1042",
      "status": "paid",
      "currency": "USD",
      "subtotal": 240000,
      "tax": 10000,
      "total": 250000,
      "issue_date": "2025-06-01",
      "due_date": "2025-06-30",
      "paid_at": "2025-06-15T09:42:11Z",
      "client": {
        "name": "Globex Corporation",
        "email": "[email protected]",
        "tax_id": "98-7654321"
      },
      "items": [
        {
          "description": "Consulting — June 2025",
          "quantity": 10,
          "unit": "HRS",
          "rate": 24000,
          "tax_rate": 10,
          "total": 264000
        }
      ]
    }
  }
}

const crypto = require('crypto');

/**
 * Verify an incoming Invoice AI webhook delivery.
 *
 * @param {string} rawBody    - The raw (unparsed) request body as a string.
 * @param {object} headers    - The request headers object.
 * @param {string} secret     - Your endpoint's signing secret (whsec_...).
 * @returns {{ ok: boolean, reason?: string }}
 */
function verifyWebhook(rawBody, headers, secret) {
  const msgId        = headers['webhook-id'];
  const msgTimestamp = headers['webhook-timestamp'];
  const msgSignature = headers['webhook-signature'];

  if (!msgId || !msgTimestamp || !msgSignature) {
    return { ok: false, reason: 'missing_headers' };
  }

  // Reject requests outside the 5-minute tolerance window.
  const now = Math.floor(Date.now() / 1000);
  const timestamp = Number(msgTimestamp);
  if (!Number.isFinite(timestamp) || Math.abs(now - timestamp) > 300) {
    return { ok: false, reason: 'timestamp_out_of_tolerance' };
  }

  // Decode the whsec_ secret.
  const secretBytes = secret.startsWith('whsec_')
    ? Buffer.from(secret.slice('whsec_'.length), 'base64url')
    : Buffer.from(secret, 'utf8');

  // Compute the expected signature.
  const signedString = `${msgId}.${msgTimestamp}.${rawBody}`;
  const expectedMac  = crypto
    .createHmac('sha256', secretBytes)
    .update(signedString)
    .digest('base64');
  const expected = `v1,${expectedMac}`;

  // The header may carry multiple space-separated signatures during key rotation.
  const presented = msgSignature.split(' ').filter(Boolean);
  const matched = presented.some((candidate) => {
    const a = Buffer.from(candidate, 'utf8');
    const b = Buffer.from(expected,   'utf8');
    if (a.length !== b.length) return false;
    return crypto.timingSafeEqual(a, b);
  });

  return matched ? { ok: true } : { ok: false, reason: 'signature_mismatch' };
}

import hashlib
import hmac
import base64
import time

def verify_webhook(raw_body: str, headers: dict, secret: str) -> dict:
    """
    Verify an incoming Invoice AI webhook delivery.

    raw_body  — the raw (unparsed) request body as a string
    headers   — a dict-like object of request headers (lowercase keys)
    secret    — your endpoint's signing secret (whsec_...)
    """
    msg_id        = headers.get('webhook-id')
    msg_timestamp = headers.get('webhook-timestamp')
    msg_signature = headers.get('webhook-signature')

    if not (msg_id and msg_timestamp and msg_signature):
        return {'ok': False, 'reason': 'missing_headers'}

    # Reject requests outside the 5-minute tolerance window.
    try:
        timestamp = int(msg_timestamp)
    except ValueError:
        return {'ok': False, 'reason': 'bad_timestamp'}

    if abs(int(time.time()) - timestamp) > 300:
        return {'ok': False, 'reason': 'timestamp_out_of_tolerance'}

    # Decode the whsec_ secret (base64url after the prefix).
    if secret.startswith('whsec_'):
        secret_bytes = base64.urlsafe_b64decode(secret[len('whsec_'):] + '==')
    else:
        secret_bytes = secret.encode('utf-8')

    # Build the signed string and compute the expected signature.
    signed_string = f"{msg_id}.{msg_timestamp}.{raw_body}".encode('utf-8')
    mac = hmac.new(secret_bytes, signed_string, hashlib.sha256).digest()
    expected = 'v1,' + base64.b64encode(mac).decode('utf-8')

    # The header may carry multiple space-separated signatures during rotation.
    presented = [s for s in msg_signature.split(' ') if s]
    matched = any(hmac.compare_digest(candidate, expected) for candidate in presented)

    return {'ok': True} if matched else {'ok': False, 'reason': 'signature_mismatch'}

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

// IMPORTANT: parse the body as raw bytes so the signature check
// runs over the exact bytes Invoice AI signed.
app.post(
  '/webhooks/invoice-ai',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const result = verifyWebhook(
      req.body.toString('utf8'),
      req.headers,
      process.env.INVOICE_AI_WEBHOOK_SECRET
    );

    if (!result.ok) {
      console.warn('Webhook rejected:', result.reason);
      return res.status(400).json({ error: result.reason });
    }

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

    switch (event.type) {
      case 'invoice.paid':
        handleInvoicePaid(event.data.object);
        break;
      case 'invoice.email_failed':
        handleEmailFailed(event.data.object);
        break;
      // ... handle other events
    }

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