Webhooks

{
  "id": "evt_001",
  "type": "batch.completed",
  "created_at": "2025-10-06T10:10:00Z",

  "batch": {
    "id": "b_abc123",
    "status": "completed",
    "project_id": "prj_123",
    "mandant_id": "m_123"
  },

  "result": {
    "download_url": "https://files.partner.example/presigned/result.zip",
    "file_size_bytes": 5242880,
    "sha256": "a3b5c7d9e1f2..."
  },

  "usage": {
    "pages": 38,
    "documents": 12,
    "total_duration_seconds": 245
  },

  "billing": {
    "partner_code": "ABC123",
    "snapshot_id": "pcs_789",
    "total_cost_eur": "17.34"
  }
}

{
  "id": "evt_002",
  "type": "batch.failed",
  "created_at": "2025-10-06T10:15:00Z",

  "batch": {
    "id": "b_abc456",
    "status": "failed",
    "project_id": "prj_123",
    "mandant_id": "m_456"
  },

  "error": {
    "code": "CONVERSION_FAILED",
    "message": "Dokument konnte nicht konvertiert werden",
    "details": "Unsupported file format: .xyz"
  }
}

import crypto from 'crypto';

export async function verifyWebhookSignature(
  request: Request,
  webhookSecret: string
): Promise<boolean> {
  // 1. Signatur aus Header extrahieren
  const signature = request.headers.get('X-SteuerMappePro-Signature');
  if (!signature) {
    throw new Error('Fehlende Webhook-Signatur');
  }

  // 2. Request Body lesen
  const body = await request.text();

  // 3. Erwartete Signatur berechnen
  const expectedSignature = `sha256=${crypto
    .createHmac('sha256', webhookSecret)
    .update(body)
    .digest('hex')}`;

  // 4. Signaturen vergleichen (timing-safe)
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';

// Webhook-Secret (aus Umgebungsvariable)
const WEBHOOK_SECRET = process.env.STEUERMAPPE_WEBHOOK_SECRET!;

// Signatur verifizieren
function verifySignature(body: string, signature: string): boolean {
  const expectedSignature = `sha256=${crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(body)
    .digest('hex')}`;

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Webhook-Handler
export async function POST(request: NextRequest) {
  try {
    // 1. Signatur aus Header extrahieren
    const signature = request.headers.get('X-SteuerMappePro-Signature');
    if (!signature) {
      return NextResponse.json(
        { error: 'Missing signature' },
        { status: 401 }
      );
    }

    // 2. Request Body lesen
    const body = await request.text();

    // 3. Signatur verifizieren
    if (!verifySignature(body, signature)) {
      return NextResponse.json(
        { error: 'Invalid signature' },
        { status: 401 }
      );
    }

    // 4. Payload parsen
    const event = JSON.parse(body);

    // 5. Event-Typ prüfen und verarbeiten
    switch (event.type) {
      case 'batch.completed':
        await handleBatchCompleted(event);
        break;

      case 'batch.failed':
        await handleBatchFailed(event);
        break;

      case 'batch.processing':
        await handleBatchProcessing(event);
        break;

      default:
        console.log(`Unbekannter Event-Typ: ${event.type}`);
    }

    // 6. Erfolgreiche Antwort
    return NextResponse.json({ received: true }, { status: 200 });

  } catch (error) {
    console.error('Webhook-Fehler:', error);
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

// Event-Handler
async function handleBatchCompleted(event: any) {
  console.log(`Batch ${event.batch.id} abgeschlossen!`);
  console.log(`Download-URL: ${event.result.download_url}`);

  // TODO: Ergebnis herunterladen und weiterverarbeiten
  // z.B. in DATEV importieren, E-Mail versenden, etc.
}

async function handleBatchFailed(event: any) {
  console.error(`Batch ${event.batch.id} fehlgeschlagen!`);
  console.error(`Fehler: ${event.error.message}`);

  // TODO: Fehlerbehandlung, z.B. Admin benachrichtigen
}

async function handleBatchProcessing(event: any) {
  console.log(`Batch ${event.batch.id} wird verarbeitet...`);
  // Optional: UI aktualisieren, Fortschritt anzeigen
}

import { prisma } from '@/lib/prisma';

async function handleBatchCompleted(event: any) {
  // Prüfen ob Event bereits verarbeitet wurde
  const existingEvent = await prisma.webhookEvent.findUnique({
    where: { eventId: event.id }
  });

  if (existingEvent) {
    console.log(`Event ${event.id} bereits verarbeitet, überspringe...`);
    return;
  }

  // Event verarbeiten
  await processResult(event.result.download_url);

  // Event als verarbeitet markieren
  await prisma.webhookEvent.create({
    data: {
      eventId: event.id,
      eventType: event.type,
      batchId: event.batch.id,
      processedAt: new Date()
    }
  });
}

# ngrok installieren (https://ngrok.com)
# Tunnel zu localhost:3000 erstellen
ngrok http 3000

# Ausgabe:
# Forwarding https://abc123.ngrok.io -> http://localhost:3000

# Webhook-URL in SteuerMappePro konfigurieren:
# https://abc123.ngrok.io/api/webhooks/steuermappe

// test-webhook-server.ts
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  console.log('Webhook empfangen:');
  console.log('Headers:', req.headers);
  console.log('Body:', JSON.stringify(req.body, null, 2));

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

app.listen(3000, () => {
  console.log('Webhook-Test-Server läuft auf http://localhost:3000');
});

// Starten:
// npx ts-node test-webhook-server.ts

{
  "batch_name": "Q4 Steuererklärungen",
  "documents": [...],
  "webhook_url": "https://api.ihr-system.de/webhooks/steuermappe",
  "webhook_secret": "ihr_geheimer_webhook_key"
}

POST /v1/webhooks
Authorization: Bearer {access_token}

{
  "url": "https://api.ihr-system.de/webhooks/steuermappe",
  "events": ["batch.completed", "batch.failed"],
  "secret": "ihr_geheimer_webhook_key"
}

import crypto from 'crypto';

function timingSafeEqual(a: string, b: string) {
  const ab = Buffer.from(a);
  const bb = Buffer.from(b);
  if (ab.length !== bb.length) return false;
  return crypto.timingSafeEqual(ab, bb);
}

export function verifyWebhook({
  bodyRaw,
  signature,
  timestamp,
  secret,
}: {
  bodyRaw: string;
  signature: string;
  timestamp: string;
  secret: string;
}) {
  // 1) Timestamp window check (±5 minutes)
  const now = Math.floor(Date.now() / 1000);
  const ts = parseInt(timestamp, 10);
  if (Number.isNaN(ts) || Math.abs(now - ts) > 300) {
    throw new Error('Timestamp outside allowed window');
  }

  // 2) Compute expected signature
  const payload = timestamp + '.' + bodyRaw;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  if (!timingSafeEqual(expected, signature)) {
    throw new Error('Invalid webhook signature');
  }
}