VAT Monitoring with Webhooks: Detect Invalid EU Registrations Automatically

curl https://api.vatnode.dev/v1/subscriptions \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vat_live_your_key_here" \
  -d '{"vatId": "DE134214316"}'

{
  "id": "sub_01hx9z3k4qw8v2r7n6m5p0y1c",
  "vatId": "DE134214316",
  "countryCode": "DE",
  "status": "active",
  "lastCheckedAt": null,
  "lastCompanyName": null,
  "lastCompanyAddress": null,
  "lastValid": null,
  "createdAt": "2026-04-23T09:15:00.000Z",
  "updatedAt": "2026-04-23T09:15:00.000Z"
}

curl https://api.vatnode.dev/v1/webhooks \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vat_live_your_key_here" \
  -d '{"url": "https://app.example.com/webhooks/vatnode"}'

{
  "id": "wh_01hx9z8m2nq4v6p3k7r0y5w9c",
  "url": "https://app.example.com/webhooks/vatnode",
  "status": "active",
  "secret": "whsec_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6",
  "createdAt": "2026-04-23T09:16:00.000Z",
  "updatedAt": "2026-04-23T09:16:00.000Z"
}

import express from 'express'
import { createHmac } from 'crypto'

const app = express()

// Use raw body middleware for this route — signature verification requires
// the exact bytes that were sent, before any JSON parsing.
app.post(
  '/webhooks/vatnode',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signatureHeader = req.headers['x-vatnode-signature'] as string | undefined
    if (!signatureHeader) {
      return res.status(401).json({ error: 'Missing signature header' })
    }

    // Parse t=<timestamp>,v1=<signature>
    const parts = Object.fromEntries(
      signatureHeader.split(',').map((part) => part.split('=') as [string, string])
    )
    const timestamp = parts['t']
    const receivedSig = parts['v1']

    if (!timestamp || !receivedSig) {
      return res.status(401).json({ error: 'Malformed signature header' })
    }

    // Reject events older than 5 minutes to prevent replay attacks
    const age = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
    if (age > 300) {
      return res.status(401).json({ error: 'Webhook timestamp too old' })
    }

    // Verify HMAC-SHA256 signature
    const webhookSecret = process.env.VATNODE_WEBHOOK_SECRET! // whsec_... from creation
    const payloadStr = req.body.toString('utf8')
    const expectedSig = createHmac('sha256', webhookSecret)
      .update(`${timestamp}.${payloadStr}`)
      .digest('hex')

    if (expectedSig !== receivedSig) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    // Signature verified — safe to parse and process
    const event = JSON.parse(payloadStr) as {
      event: string
      data: {
        vatId: string
        countryCode: string
        subscriptionId: string
        previousState?: string
        newState?: string
        previousName?: string
        newName?: string
        previousAddress?: string
        newAddress?: string
      }
      timestamp: string
    }

    // Always respond 200 before doing any async work
    res.status(200).json({ received: true })

    // Handle event types
    switch (event.event) {
      case 'VAT_BECAME_INVALID': {
        const { vatId, countryCode } = event.data
        console.log(`VAT number ${vatId} (${countryCode}) is no longer valid`)

        // Pause reverse charge billing for this customer
        await billingService.pauseReverseCharge(vatId)

        // Alert the finance team
        await notificationService.notify({
          channel: 'finance-alerts',
          message: `Customer VAT number ${vatId} has become invalid. Billing paused pending review.`,
        })
        break
      }

      case 'VAT_BECAME_VALID': {
        const { vatId } = event.data
        console.log(`VAT number ${vatId} is now valid again`)
        // Resume reverse charge billing after re-confirming with your team
        await billingService.resumeReverseCharge(vatId)
        break
      }

      case 'COMPANY_NAME_CHANGED': {
        const { vatId, newName } = event.data
        console.log(`Company name for ${vatId} changed to: ${newName}`)
        await customerService.updateCompanyName(vatId, newName ?? null)
        break
      }

      case 'COMPANY_ADDRESS_CHANGED': {
        const { vatId, newAddress } = event.data
        console.log(`Company address for ${vatId} changed to: ${newAddress}`)
        await customerService.updateCompanyAddress(vatId, newAddress ?? null)
        break
      }

      default:
        console.log(`Unhandled vatnode event: ${event.event}`)
    }
  }
)

app.listen(3000)

{
  "event": "VAT_BECAME_INVALID",
  "data": {
    "vatId": "DE134214316",
    "countryCode": "DE",
    "subscriptionId": "sub_01hx9z3k4qw8v2r7n6m5p0y1c",
    "previousState": "valid",
    "newState": "invalid"
  },
  "timestamp": "2026-04-23T07:04:12.381Z"
}