Wie funktionieren Webhooks? Events abonnieren, Signatur prüfen, Wiederholungen

Wie funktionieren Webhooks? Events abonnieren, Signatur prüfen, Wiederholungen

Statt ständig die API abzufragen, kannst du dir von REST API Pro Ereignisse aktiv zuschicken lassen. Sobald in Perfex etwas passiert, pusht das Modul die Daten als signiertes JSON an eine URL deiner Wahl, ideal für Zapier, Make oder eigene Systeme.

📣 57 Events abonnieren

Es stehen 57 CRM-Events zur Verfügung, zum Beispiel neue Rechnung, Rechnung bezahlt, neuer Lead, Lead konvertiert oder Ticket-Antwort. So richtest du einen Webhook ein:

1. Öffne REST API Pro → Webhooks und klicke auf Webhook erstellen.
2. Gib einen Namen und die Payload-URL an, also den HTTPS-Endpunkt, der das JSON empfängt. Private oder interne Adressen werden aus Sicherheitsgründen blockiert (SSRF-Schutz).
3. Wähle die Events, die du empfangen willst (einzeln oder alle).
4. Speichern, fertig. Mit Testereignis senden prüfst du die Anbindung sofort.

🔏 Signatur prüfen (HMAC)

Jede Zustellung ist mit dem Webhook-Secret per HMAC signiert und trägt den Header X-Rap-Signature . Damit stellst du auf deinem Server sicher, dass die Anfrage wirklich von deinem Perfex stammt und unterwegs nicht verändert wurde. Das Prinzip: Du berechnest aus dem empfangenen Payload und deinem Secret selbst die HMAC-Signatur und vergleichst sie mit dem Header. Ein einfaches Beispiel in PHP:

$payload = file_get_contents('php://input'); $signature = hash_hmac('sha256', $payload, 'DEIN_WEBHOOK_SECRET'); if (hash_equals($signature, $_SERVER['HTTP_X_RAP_SIGNATURE'])) { // Signatur gueltig - Payload verarbeiten }

Das passende Secret findest du direkt beim jeweiligen Webhook in der Verwaltung. Auf der Webhook-Seite ist der Verifizierungs-Codeausschnitt außerdem hinterlegt.

🔁 Wiederholungen & Backoff

Antwortet dein Endpunkt nicht oder mit einem Fehler, gibt REST API Pro nicht sofort auf: Zustellungen laufen über eine Queue mit automatischen Wiederholungen und wachsendem Abstand (Backoff), sodass kurze Ausfälle deines Systems keine Events verschlucken. Die maximale Anzahl der Versuche und das Timeout stellst du in den Einstellungen ein.

📊 Delivery-Log

Jede Zustellung landet im Delivery-Log mit Status (zugestellt, ausstehend, fehlgeschlagen), Anzahl der Versuche und HTTP-Antwort. Fehlgeschlagene oder ausgewählte Zustellungen kannst du per Erneut senden von Hand neu anstoßen.

⏱️ Hinweis zum Cron

Die Zustellung läuft über den Perfex-Cron (mit Inline-Fallback, falls der Cron länger stillsteht). Für zuverlässige Webhooks sollte der Cron also eingerichtet sein, die Health-Card in den Einstellungen zeigt den Status an.