Webhooks

Übersicht

Webhooks ermöglichen es dir, in Echtzeit über Ereignisse in deinem Lymbe AI Account benachrichtigt zu werden. Wenn ein Event eintritt (z. B. ein neuer Lead), sendet Lymbe AI eine HTTP-POST-Anfrage an deine konfigurierte URL.

Webhook einrichten

1. Gehe im Dashboard zu Einstellungen → Webhooks
2. Klicke auf „Neuen Webhook erstellen"
3. Gib die Ziel-URL ein (muss HTTPS sein)
4. Wähle die Events aus, die du empfangen möchtest
5. Optional: Vergib ein Webhook-Secret für die Signatur-Verifizierung
6. Klicke auf „Speichern"

Verfügbare Events

Payload-Format

Alle Webhook-Payloads haben eine einheitliche Struktur:

{
  "id": "evt_abc123def456",
  "type": "lead.created",
  "timestamp": "2026-03-18T14:30:00Z",
  "tenantId": "t_abc123",
  "data": {
    "lead": {
      "id": "lead_xyz789",
      "name": "Lisa Schmidt",
      "email": "lisa@example.com",
      "phone": "+49 151 98765432",
      "company": "Schmidt & Partner",
      "message": "Wir suchen eine Chatbot-Lösung für 3 Websites",
      "botId": "bot_xyz789",
      "conversationId": "conv_abc123",
      "source": "widget",
      "status": "new",
      "createdAt": "2026-03-18T14:30:00Z"
    }
  }
}

conversation.created Payload

{
  "id": "evt_conv001",
  "type": "conversation.created",
  "timestamp": "2026-03-18T14:25:00Z",
  "tenantId": "t_abc123",
  "data": {
    "conversation": {
      "id": "conv_new123",
      "botId": "bot_xyz789",
      "status": "active",
      "visitorInfo": {
        "ip": "203.0.113.42",
        "userAgent": "Mozilla/5.0...",
        "page": "https://example.com/preise"
      },
      "startedAt": "2026-03-18T14:25:00Z"
    }
  }
}

handover.requested Payload

{
  "id": "evt_ho001",
  "type": "handover.requested",
  "timestamp": "2026-03-18T14:35:00Z",
  "tenantId": "t_abc123",
  "data": {
    "conversationId": "conv_abc123",
    "botId": "bot_xyz789",
    "reason": "user_request",
    "visitorName": "Lisa Schmidt",
    "lastMessage": "Ich möchte mit einem Mitarbeiter sprechen."
  }
}

Signatur-Verifizierung

Jeder Webhook-Request enthält einen X-Lymbe-Signature Header. Damit kannst du sicherstellen, dass der Request tatsächlich von Lymbe AI stammt. Die Signatur wird mit HMAC-SHA256 und deinem Webhook-Secret berechnet.

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

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

// Verwendung in einem Express-Handler
app.post('/webhooks/lymbe', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-lymbe-signature'] as string;
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, signature, process.env.LYMBE_WEBHOOK_SECRET!)) {
    console.error('Ungültige Webhook-Signatur');
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(payload);
  console.log('Webhook empfangen:', event.type);

  // Event verarbeiten
  switch (event.type) {
    case 'lead.created':
      handleNewLead(event.data.lead);
      break;
    case 'conversation.completed':
      handleCompletedConversation(event.data.conversation);
      break;
    case 'handover.requested':
      notifyAgents(event.data);
      break;
  }

  // Immer 200 zurückgeben um den Empfang zu bestätigen
  res.status(200).json({ received: true });
});

Retry-Policy

Wenn dein Endpunkt nicht mit einem 2xx-Statuscode antwortet, wiederholt Lymbe AI die Zustellung nach einem exponentiellen Backoff:

Nach 6 fehlgeschlagenen Versuchen wird das Event als „failed" markiert. Fehlgeschlagene Events können im Dashboard unter Einstellungen → Webhooks → Event-Log eingesehen und manuell erneut gesendet werden.

Best Practices

• Verifiziere immer die Signatur, bevor du ein Event verarbeitest
• Antworte sofort mit 200 OK und verarbeite das Event asynchron
• Implementiere Idempotenz – das gleiche Event kann mehrfach zugestellt werden
• Speichere die Event-ID (id Feld), um Duplikate zu erkennen
• Logge alle eingehenden Webhook-Requests für Debugging-Zwecke
• Verwende HTTPS für deinen Webhook-Endpunkt
• Überwache fehlgeschlagene Webhooks im Dashboard