So funktionieren Webhooks - Enrow API Documentation

Warum Webhooks verwenden?

Mit Webhooks kommen die Ergebnisse zu Ihnen, anstatt dass Sie sie wiederholt abfragen müssen. Statt einen GET-Endpunkt so lange abzufragen, bis eine Suche abgeschlossen ist, sendet Enrow jedes Ergebnis in dem Moment an Ihren Server, in dem es bereit ist — das spart Anfragen, reduziert die Latenz und hält Ihren Code einfach. Verschwenden Sie keine Anfragen mehr — lassen Sie die Ergebnisse zu Ihnen kommen. Da jeder Enrow-Endpunkt asynchron ist, sind Webhooks die empfohlene Methode, um Ergebnisse über Email Finder, Email Verifier und Phone Finder hinweg zu erhalten. Webhooks umgehen außerdem die Ratenbegrenzungen vollständig, da Enrow Sie aufruft und nicht umgekehrt.

Wie läuft ein Webhook-Ablauf ab?

Ein Webhook-Ablauf macht aus einer einzelnen Suchanfrage eine automatische Zustellung. Sie teilen Enrow mit, wohin die Ergebnisse gesendet werden sollen, und Enrow erledigt den Rest:

Sie senden eine Suchanfrage per POST mit einer webhook-URL in den settings
Enrow gibt sofort eine Such-ID zurück
Enrow verarbeitet die Suche im Hintergrund
Nach Abschluss sendet Enrow die Ergebnisse per POST an Ihre Webhook-URL

Wie richte ich einen Webhook ein?

Sie können einen Webhook auf zwei Arten registrieren, je nachdem, ob Sie ihn für eine einzelne Suche oder für jede Suche verwenden möchten:

Pro Anfrage: Fügen Sie eine webhook-URL in das settings-Objekt eines beliebigen API-Aufrufs ein
Global: Legen Sie auf der API-Seite des Dashboards einen Standard-Webhook fest. Enrow prüft die URL beim Speichern: siehe Wie verifiziere ich meinen Webhook-Endpunkt?

{
  "fullname": "Dwight Schrute",
  "company_domain": "dundermifflin.com",
  "settings": {
    "webhook": "https://your-app.com/webhooks/enrow"
  }
}

Enthält eine Anfrage einen eigenen webhook, hängt es vom Endpunkt ab, was mit dem Standard-Webhook geschieht:

Email Finder: Enrow benachrichtigt beide URLs (nur einmal, wenn sie identisch sind)
Phone Finder und Email Verifier: Die URL pro Anfrage ersetzt den Standard-Webhook

Ihr Webhook-Endpunkt muss öffentlich erreichbar sein und einen 2xx-Statuscode zurückgeben. Verwenden Sie HTTPS: HTTP-URLs werden zwar akzeptiert, aber nicht empfohlen. Enrow sendet jede Benachrichtigung nur einmal und wiederholt eine fehlgeschlagene Zustellung nicht. Sie können jedoch jederzeit auf den passenden GET-Endpunkt zurückgreifen.

Wie verifiziere ich meinen Webhook-Endpunkt?

Wenn Sie auf der API-Seite eine neue Standard-Webhook-URL speichern, sendet Enrow zunächst eine einmalige Verifizierungsanfrage an diese URL, um zu bestätigen, dass Sie den Endpunkt kontrollieren. Die URL wird nur gespeichert, wenn Ihr Endpunkt korrekt darauf antwortet. Enrow sendet eine POST-Anfrage mit diesem JSON-Body:

{
  "event": "endpoint_verification",
  "challenge": "3f9c1e2a-7b4d-4c8e-9a51-2d6f0b7e8c13"
}

Ihr Endpunkt muss innerhalb von 5 Sekunden mit einem 2xx-Statuscode antworten und denselben challenge-Wert zurücksenden, entweder direkt als Antwort-Body oder als JSON:

{
  "challenge": "3f9c1e2a-7b4d-4c8e-9a51-2d6f0b7e8c13"
}

Zum Beispiel mit Node.js und Express:

app.post('/webhooks/enrow', express.json(), (req, res) => {
  if (req.body.event === 'endpoint_verification') {
    return res.json({ challenge: req.body.challenge });
  }
  res.sendStatus(200);
  // Then process the result in the background
});

Schlägt die Prüfung fehl, zeigt die App den Grund an (keine Antwort innerhalb von 5 Sekunden, ein anderer Status als 2xx, ein nicht übereinstimmender challenge-Wert, eine nicht erreichbare URL oder eine private bzw. interne Adresse), und Ihr aktueller Webhook bleibt aktiv. Ein webhook, der in den settings einer Anfrage übergeben wird, wird nicht auf diese Weise geprüft.

Welche Ereignisse lösen einen Webhook-Aufruf aus?

Sechs Arten von Ereignissen können einen Webhook-Aufruf auslösen, eines pro Endpunkt und Suchtyp:

Ereignis	Beschreibung
`single_search_finished`	Eine einzelne E-Mail-Suche wurde abgeschlossen
`bulk_search_finished`	Eine E-Mail-Sammelsuche wurde abgeschlossen
`verification_finished`	Eine einzelne E-Mail-Verifizierung wurde abgeschlossen
`bulk_verification_finished`	Eine E-Mail-Sammelverifizierung wurde abgeschlossen
`single_phone_search_finished`	Eine einzelne Telefonsuche wurde abgeschlossen
`bulk_phone_search_finished`	Eine Telefon-Sammelsuche wurde abgeschlossen

Wie sieht ein Webhook-Payload aus?

Der Webhook-Payload hängt vom Endpunkt ab und davon, ob es sich um eine einzelne Suche oder eine Sammelsuche handelt. Einzelsuchen liefern das vollständige Ergebnis direkt, während Sammelsuchen eine Abschlussbenachrichtigung liefern, der Sie mit einer GET-Anfrage nachgehen.

Email Finder — Einzeln

Bei Einzelsuchen erhalten Sie das vollständige Ergebnis direkt in der Webhook-Benachrichtigung. Dadurch entfällt die Notwendigkeit, eine GET-Anfrage durchzuführen.

{
  "event": "single_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "credits": {
    "cost": 1
  },
  "result": {
    "email": "dwight.schrute@dundermifflin.com",
    "qualification": "valid",
    "custom": "your_custom_data",
    "info": {
      "company_domain": "dundermifflin.com",
      "fullname": "Dwight Schrute",
      "firstname": "Dwight",
      "lastname": "Schrute"
    }
  }
}

Suche anhand einer LinkedIn-Profil-URL

Bei einer Suche, die anhand einer LinkedIn-Profil-URL gestartet wurde, enthält result zusätzlich linkedin_status und linkedin_url (die von Ihnen gesendete URL). info ist nur enthalten, wenn eine E-Mail gefunden wird: Eine Suche ohne Treffer nennt die Person nie. credits.cost enthält die endgültigen Kosten, wie credits_used in der GET-Antwort, die auch jeden linkedin_status erklärt.

{
  "event": "single_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "credits": {
    "cost": 1
  },
  "result": {
    "email": "dwight.schrute@dundermifflin.com",
    "qualification": "valid",
    "linkedin_status": "found",
    "linkedin_url": "https://www.linkedin.com/in/dwight-schrute",
    "custom": { "crm_id": "lead_001" },
    "info": {
      "company_domain": "dundermifflin.com",
      "company_name": "Dunder Mifflin",
      "fullname": "Dwight Schrute",
      "firstname": "Dwight",
      "lastname": "Schrute"
    }
  }
}

{
  "event": "single_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "credits": {
    "cost": 0.25
  },
  "result": {
    "qualification": "invalid",
    "linkedin_status": "no_current_company",
    "linkedin_url": "https://www.linkedin.com/in/dwight-schrute",
    "custom": { "crm_id": "lead_001" }
  }
}

Email Finder — Sammel

Bei Sammelsuchen erhalten Sie eine Benachrichtigung, dass der Batch abgeschlossen ist. Rufen Sie anschließend den Endpunkt GET /email/find/bulk mit der id auf, um die Ergebnisse abzurufen.

{
  "event": "bulk_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "credits": {
    "cost": 2284
  }
}

Email Verifier — Einzeln

Das vollständige Ergebnis ist direkt enthalten — keine GET-Anfrage erforderlich.

{
  "event": "verification_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "email": "pam.beesly@dundermifflin.com",
  "qualification": "valid",
  "custom": "your_custom_data"
}

Email Verifier — Sammel

Dies ist nur eine Benachrichtigung. Rufen Sie GET /email/verify/bulk mit der id auf, um die Ergebnisse abzurufen.

{
  "event": "bulk_verification_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "credits": {
    "cost": 386.25
  }
}

Phone Finder — Einzeln

Das vollständige Ergebnis ist direkt enthalten — keine GET-Anfrage erforderlich.

{
  "event": "single_phone_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "result": {
    "number": "+15705551234",
    "params": {
      "linkedin_url": "https://www.linkedin.com/in/michael-scott"
    },
    "qualification": "found"
  }
}

Phone Finder — Sammel

Dies ist nur eine Benachrichtigung. Rufen Sie GET /phone/bulk mit der id auf, um die Ergebnisse abzurufen.

{
  "event": "bulk_phone_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt"
}

Worin unterscheiden sich Einzel- und Sammel-Webhooks?

Webhooks für Einzelsuchen enthalten das vollständige Ergebnis, sodass kein zusätzlicher Aufruf erforderlich ist. Webhooks für Sammelsuchen signalisieren nur, dass der Batch abgeschlossen ist — Sie rufen die Ergebnisse anschließend mit dem passenden GET-Endpunkt ab.

Typ	Einzelsuchen	Sammelsuchen
Payload	Vollständiges Ergebnis enthalten	Nur Benachrichtigung (ID, dazu Credits außer bei Telefonsuchen)
GET erforderlich?	Nein	Ja — verwenden Sie den GET-Endpunkt mit der `id`

Bei Einzelsuchen enthält der Webhook alles, was Sie benötigen. Bei Sammelsuchen teilt Ihnen der Webhook mit, dass der Batch abgeschlossen ist — anschließend rufen Sie die Ergebnisse ab.

Was sind die Best Practices für Webhook-Endpunkte?

Ein zuverlässiger Webhook-Endpunkt antwortet schnell, verwendet HTTPS und toleriert gelegentliche Duplikate. Befolgen Sie diese Praktiken, um zuverlässige Zustellungen sicherzustellen:

Schnell 200 zurückgeben

Verarbeiten Sie Webhook-Payloads asynchron. Geben Sie sofort einen 200 zurück und verarbeiten Sie die Daten anschließend in einem Hintergrundjob.

HTTPS verwenden

Verwenden Sie einen HTTPS-Endpunkt, damit die Ergebnisse verschlüsselt übertragen werden. HTTP-URLs werden zwar akzeptiert, aber nicht empfohlen.

Duplikate behandeln

In seltenen Fällen können Webhooks mehr als einmal zugestellt werden. Verwenden Sie das Feld id, um Duplikate zu entfernen.

Benutzerdefinierte Felder verwenden

Übergeben Sie custom-Daten in Ihren Anfragen, um zu identifizieren, zu welchem Datensatz ein Webhook-Ergebnis gehört:

{
  "fullname": "Dwight Schrute",
  "company_domain": "dundermifflin.com",
  "custom": { "crm_id": "lead_001" }
}

Das Feld custom wird unverändert im Webhook-Payload zurückgegeben.

Sollte ich Webhooks oder Polling verwenden?

Verwenden Sie Webhooks für die Produktion und Polling nur für schnelles Prototyping oder zum Debuggen. Webhooks liefern Ergebnisse in Echtzeit, ohne Ihr Anfragekontingent zu verbrauchen, während Polling wiederholte GET-Aufrufe durchführt, die auf Ihre Ratenbegrenzungen angerechnet werden.

	Webhooks	Polling (GET)
Latenz	Echtzeit	Abhängig vom Abfrageintervall
API-Aufrufe	0 (Enrow ruft Sie auf)	Mehrere Aufrufe pro Suche
Auswirkung auf Rate-Limit	Keine	Verbraucht Kontingent
Komplexität	Erfordert Endpunkt-Einrichtung	Einfacher umzusetzen

Wir empfehlen Webhooks für den Produktiveinsatz. Verwenden Sie Polling nur für schnelles Prototyping oder zum Debuggen.

FAQ

Kosten Webhooks zusätzliche Credits?

Nein. Webhooks verbrauchen keine zusätzlichen Credits: Sie zahlen nur für die Suche selbst. Die Payloads von Email Finder und Email Verifier geben die Credit-Kosten im Feld credits.cost an. Es sind die endgültigen Kosten nach Erstattungen: 0 für eine Einzelsuche ohne Ergebnis (0.25 für eine E-Mail-Suche anhand einer LinkedIn-Profil-URL oder für ein Konto mit ungewöhnlich niedriger Erfolgsquote) und bei einer Bulk-Suche die gefundenen Zeilen plus die berechneten Fehlschläge. Die Payloads des Phone Finder enthalten die Kosten nicht. Siehe Credits & Abrechnung für die Kosten pro Endpunkt.

Was passiert, wenn mein Endpunkt keine 200 zurückgibt?

Enrow sendet jede Benachrichtigung nur einmal. Wenn Ihr Server nicht erreichbar ist oder mit einem anderen Status als 2xx antwortet, schlägt die Zustellung fehl und wird nicht wiederholt. Sie können die Ergebnisse jederzeit abrufen, indem Sie den entsprechenden GET-Endpunkt mit der Such-id abfragen.

Wie ordne ich einen Webhook der ursprünglichen Anfrage zu?

Verwenden Sie die id aus der Suchantwort oder übergeben Sie ein custom-Objekt in Ihrer Anfrage — es wird unverändert im Webhook-Payload zurückgegeben, sodass Sie Ergebnisse Ihren eigenen Datensätzen zuordnen können, etwa einer CRM-Lead-ID.

Warum habe ich keinen Webhook erhalten?

Die häufigsten Ursachen sind ein Endpunkt, der keinen 2xx-Status zurückgibt, ein Server mit Zeitüberschreitung oder eine URL, die nicht öffentlich erreichbar ist. Fehlgeschlagene Zustellungen werden nicht wiederholt: Rufen Sie das Ergebnis mit dem passenden GET-Endpunkt und der Such-id ab. Für eine umfassendere Fehlerbehebung siehe Fehlerbehandlung und Statuscodes.

Nächste Schritte

E-Mail finden

Übergeben Sie eine Webhook-URL in den Settings, um das Ergebnis automatisch zugestellt zu bekommen.

Sammelergebnisse abrufen

Rufen Sie Batch-Ergebnisse ab, nachdem ein bulk_search_finished-Webhook ausgelöst wurde.

Authentifizierung

So übergeben Sie Ihren API-Schlüssel im x-api-key-Header.

Ratenbegrenzungen

Erfahren Sie, warum Webhooks das Anfragekontingent vermeiden, das Polling verbraucht.

​Warum Webhooks verwenden?

​Wie läuft ein Webhook-Ablauf ab?

​Wie richte ich einen Webhook ein?

​Wie verifiziere ich meinen Webhook-Endpunkt?

​Welche Ereignisse lösen einen Webhook-Aufruf aus?

​Wie sieht ein Webhook-Payload aus?

​Email Finder — Einzeln

​Suche anhand einer LinkedIn-Profil-URL

​Email Finder — Sammel

​Email Verifier — Einzeln

​Email Verifier — Sammel

​Phone Finder — Einzeln

​Phone Finder — Sammel

​Worin unterscheiden sich Einzel- und Sammel-Webhooks?

​Was sind die Best Practices für Webhook-Endpunkte?

​Sollte ich Webhooks oder Polling verwenden?

​FAQ

​Nächste Schritte

E-Mail finden

Sammelergebnisse abrufen

Authentifizierung

Ratenbegrenzungen

Warum Webhooks verwenden?

Wie läuft ein Webhook-Ablauf ab?

Wie richte ich einen Webhook ein?

Wie verifiziere ich meinen Webhook-Endpunkt?

Welche Ereignisse lösen einen Webhook-Aufruf aus?

Wie sieht ein Webhook-Payload aus?

Email Finder — Einzeln

Suche anhand einer LinkedIn-Profil-URL

Email Finder — Sammel

Email Verifier — Einzeln

Email Verifier — Sammel

Phone Finder — Einzeln

Phone Finder — Sammel

Worin unterscheiden sich Einzel- und Sammel-Webhooks?

Was sind die Best Practices für Webhook-Endpunkte?

Sollte ich Webhooks oder Polling verwenden?

FAQ

Nächste Schritte