Wenn du Probleme mit deinem Webhook-Setup hast, bietet dir dieser Leitfaden einen Überblick über häufige Fehlermeldungen, die vom Zielsystem zurückgegeben werden (z. B. dein eigener Server oder ein Drittanbieterdienst), sowie empfohlene Schritte zur Fehlerbehebung.

❗ Wichtig: Diese Fehler stammen nicht von Heyflow, sondern werden vom konfigurierten Webhook-Endpunkt generiert. Es ist daher wichtig, die Logik deines externen Servers zu überprüfen, um die Ursache des Fehlers, der durch eingehende HTTP-Anfragen von Heyflow ausgelöst wird, genau zu identifizieren.

🔎 Für eine Übersicht der Error Codes schaue hier vorbei.

Allgemeine Empfehlungen

Stelle sicher, dass URLs und Endpunkte korrekt geschrieben und erreichbar sind.
Nutze Webhook-Testtools während der Entwicklung.
Überwache DNS- oder Verbindungsprobleme – insbesondere bei extern gehosteten Diensten.
Implementiere Fehlerprotokollierung mit Response-IDs zur schnellen Nachverfolgung von Problemen.

getaddrinfo EAI_AGAIN / getaddrinfo ENOTFOUND

Beschreibung: DNS-Auflösungsfehler. Dies weist in der Regel auf ein temporäres Problem bei der Namensauflösung hin.

Lösungen:

Stelle sicher, dass die Domain korrekt ist (z. B. heyflow-webhook-...run.app). Schon kleine Tippfehler verhindern die erfolgreiche Auflösung des Endpunkts.
Prüfe, ob Internet- oder DNS-Probleme vorliegen. DNS funktioniert wie ein Telefonbuch für das Internet. Bei einer Störung kann der Zielserver nicht gefunden werden.
Warte einige Minuten und versuche es erneut. Teste, ob andere Websites laden, und starte ggf. deinen Router neu.
Verwende – wenn möglich – eine zuverlässigere oder statische Domain.
Wenn du die Nutzlast manuell erstellst, achte auf korrektes JSON-Format. Bitte deinen Entwickler, die Struktur zu prüfen, falls nötig.

AxiosError: Request failed with status code 400

eschreibung: Bad Request – Wahrscheinlich durch fehlerhaftes JSON, fehlende Pflichtfelder oder falsche Content-Type-Header.

Lösungen:

Validieren der Nutzlast: Stelle sicher, dass das gesendete Format dem erwarteten des Zielservers entspricht (z. B. korrektes JSON). Nutze Online-Tools wie JSONLint zur Prüfung.
Überprüfe, ob alle Pflichtfelder vorhanden und korrekt benannt sind.
Teste den Webhook mit webhook.site, um die gesendeten Daten vorab zu überprüfen.

AxiosError: Request failed with status code 401

Beschreibung: Unauthorized Request – Fehlende oder ungültige Authentifizierung.

Lösungen:

Überprüfe, ob Authentifizierungsdaten (z. B. API-Key, Token oder Zugangsdaten) korrekt in den Headern übermittelt werden.

AxiosError: Request failed with status code 404

Beschreibung: Not Found – Die Ziel-URL ist möglicherweise falsch oder nicht erreichbar.

Lösungen:

Vergewissere dich, dass die Anfrage an die korrekte Adresse mit dem richtigen Ressourcenpfad und der richtigen HTTP-Methode (z. B. GET, POST) gesendet wird.

AxiosError: Request failed with status code 409

Beschreibung: Conflict – Es wird versucht, eine Ressource doppelt zu erstellen.

Lösungen:

Prüfe, ob die Ressource bereits existiert (z. B. Kontakt oder Lead).
Verwende nach Möglichkeit eine Upsert-Funktion, um bestehende Daten zu aktualisieren, anstatt sie neu anzulegen.

AxiosError: Request failed with status code 422

Beschreibung: Unprocessable Entity – Die Daten haben das richtige Format, sind aber inhaltlich ungültig (z. B. fehlerhafte E-Mail-Adresse).

Lösungen:

Überprüfe die übermittelten Datenformate. Beispiel: gültige E-Mail-Adresse ([email protected]) oder ausreichende Länge der Telefonnummer.
Nutze native Input-Validierungen in Heyflow für eine bessere Dateneingabe.

AxiosError: Request failed with status code 500

Beschreibung: Internal Server Error – Ein Problem auf dem Zielserver.

Lösungen:

Wiederhole die Anfrage zu einem späteren Zeitpunkt.
Wende dich an den API-Anbieter mit der Response-ID zur Fehleranalyse.

Error: connect ETIMEDOUT

Beschreibung: Verbindungszeitüberschreitung – Der externe Dienst reagiert nicht rechtzeitig.

Lösungen:

Prüfe deine Internetverbindung oder deinen Hosting-Service.
Der Zielserver könnte vorübergehend nicht erreichbar sein – versuche es später erneut.
Falls unterstützt, erhöhe die Timeout-Einstellungen.