Webhooks

Webhooks ermöglichen es SilentChat, Echtzeit-Ereignisbenachrichtigungen an Ihren Server zu senden. Anstatt die API abzufragen, erhält Ihre Anwendung eine HTTP-POST-Anfrage, wenn ein Ereignis eintritt.

Webhook einrichten

1. Gehen Sie im Dashboard zu Einstellungen → Webhooks und klicken Sie auf Neuer Webhook.
2. Geben Sie die HTTPS-URL Ihres Endpunkts ein.
3. Wählen Sie die Ereignisse aus, die Sie empfangen möchten.
4. Klicken Sie auf Speichern. SilentChat sendet sofort ein Test-Ping-Ereignis, um zu prüfen, ob der Endpunkt erreichbar ist.

Verfügbare Ereignisse

Payload-Format

Jede Webhook-Anfrage ist ein HTTP-POST mit einem JSON-Body und dem Header Content-Type: application/json. Die übergeordnete Struktur ist bei allen Ereignissen einheitlich:

{
  "id": "evt_01HXY3ABC",
  "type": "message.created",
  "tenant_id": "tn_abc123",
  "created_at": "2025-10-12T14:35:00Z",
  "data": {
    "conversation_id": "conv_01HXYZ",
    "message_id": "msg_01HXYZ",
    "sender_type": "visitor",
    "text": "Hi, I need help with my order."
  }
}

Webhook-Anfrage-Header

Signatur verifizieren

Jede Webhook-Anfrage enthält einen X-SilentChat-Signature-Header mit einer HMAC-SHA256-Signatur. Verifizieren Sie diese Signatur immer, um zu bestätigen, dass die Anfrage von SilentChat stammt und nicht manipuliert wurde.

Verifikationsbeispiel (Node.js)

const crypto = require('crypto');

function verifySignature(secret, body, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

// In your request handler:
app.post('/webhooks/silentchat', (req, res) => {
  const signature = req.headers['x-silentchat-signature'];
  const rawBody = req.rawBody; // raw request body as a string

  if (!verifySignature(process.env.SC_WEBHOOK_SECRET, rawBody, signature)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;
  console.log('Received event:', event.type);

  // Process the event ...

  res.status(200).send('OK');
});

Verifikationsbeispiel (Python)

import hmac
import hashlib
import os
from flask import Flask, request, abort

app = Flask(__name__)

def verify_signature(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.route('/webhooks/silentchat', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-SilentChat-Signature', '')
    raw_body = request.get_data()

    if not verify_signature(os.environ['SC_WEBHOOK_SECRET'], raw_body, signature):
        abort(401)

    event = request.get_json()
    print(f"Received event: {event['type']}")

    # Process the event ...

    return 'OK', 200

Wiederholungsrichtlinie

Wenn Ihr Endpunkt nicht innerhalb von 10 Sekunden mit einem 2xx-Status antwortet, wiederholt SilentChat die Zustellung mit exponentiellem Backoff:

Nach fünf fehlgeschlagenen Versuchen wird die Webhook-Zustellung als fehlgeschlagen markiert. Sie können fehlgeschlagene Zustellungen unter Einstellungen → Webhooks → Zustellungsprotokoll einsehen und erneut auslösen.

Wenn ein Endpunkt dauerhaft fehlschlägt (mehr als 100 aufeinanderfolgende Fehler), wird er automatisch deaktiviert und Sie erhalten eine E-Mail-Benachrichtigung.

Best Practices

• Antworten Sie sofort mit 200 OK und verarbeiten Sie das Ereignis asynchron, um Timeout-Fehler zu vermeiden.
• Machen Sie Ihren Handler idempotent — SilentChat kann dasselbe Ereignis mehr als einmal zustellen.
• Verifizieren Sie immer die Signatur, bevor Sie eine Nutzlast verarbeiten.
• Filtern Sie Ereignisse auf der Webhook-Konfigurationsebene, anstatt sie im Code zu ignorieren.
• Verwenden Sie das Zustellungsprotokoll im Dashboard, um fehlgeschlagene Ereignisse während der Entwicklung einzusehen und erneut auszulösen.