Jak działają webhooki

Po co używać webhooków?

Webhooki sprawiają, że wyniki trafiają do Ciebie, zamiast tego, żebyś wielokrotnie o nie pytał. Zamiast odpytywać endpoint GET aż do zakończenia wyszukiwania, Enrow wysyła każdy wynik na Twój serwer w momencie, gdy jest gotowy — oszczędzając żądania, zmniejszając opóźnienia i utrzymując prostotę kodu. Przestań marnować żądania — pozwól, aby wyniki same do Ciebie trafiały. Ponieważ każdy endpoint Enrow jest asynchroniczny, webhooki są zalecanym sposobem otrzymywania wyników w Email Finder, Email Verifier oraz Phone Finder. Webhooki całkowicie omijają również limity szybkości, ponieważ to Enrow wywołuje Ciebie, a nie odwrotnie.

Jak przebiega proces webhooka?

Proces webhooka zamienia pojedyncze żądanie wyszukiwania w automatyczne dostarczenie. Mówisz Enrow, dokąd wysłać wyniki, a Enrow robi resztę:

Wysyłasz POST z żądaniem wyszukiwania z adresem URL webhook w settings
Enrow natychmiast zwraca ID wyszukiwania
Enrow przetwarza wyszukiwanie w tle
Po zakończeniu Enrow wysyła POST z wynikami na Twój adres URL webhooka

Jak skonfigurować webhooka?

Webhooka możesz zarejestrować na dwa sposoby, w zależności od tego, czy chcesz go dla jednego wyszukiwania, czy dla każdego:

Dla pojedynczego żądania: Dołącz adres URL webhook w obiekcie settings dowolnego wywołania API
Globalnie: Ustaw domyślny webhook na stronie API w panelu. Enrow sprawdza adres URL podczas jego zapisywania: zobacz Jak zweryfikować swój endpoint webhooka?

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

Gdy żądanie zawiera własny parametr webhook, od endpointu zależy, co dzieje się z webhookiem domyślnym:

Email Finder: Enrow powiadamia oba adresy URL (raz, jeśli są takie same)
Phone Finder i Email Verifier: adres URL podany w żądaniu zastępuje adres domyślny

Twój endpoint webhooka musi być publicznie osiągalny i zwracać kod statusu 2xx. Używaj HTTPS: zwykłe adresy URL HTTP są akceptowane, ale niezalecane. Enrow wysyła każde powiadomienie jeden raz i nie ponawia nieudanego dostarczenia, więc jako rozwiązanie awaryjne zawsze możesz użyć odpowiedniego endpointu GET.

Jak zweryfikować swój endpoint webhooka?

Gdy zapisujesz nowy domyślny adres URL webhooka na stronie API, Enrow najpierw wysyła na niego jednorazowe żądanie weryfikacyjne, aby potwierdzić, że kontrolujesz ten endpoint. Adres URL zostaje zapisany tylko wtedy, gdy Twój endpoint poprawnie na nie odpowie. Enrow wysyła żądanie POST z następującą treścią JSON:

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

Twój endpoint musi odpowiedzieć w ciągu 5 sekund kodem statusu 2xx i odesłać tę samą wartość challenge, jako surową treść odpowiedzi albo w formacie JSON:

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

Na przykład w Node.js z 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
});

Jeśli weryfikacja się nie powiedzie, aplikacja pokaże przyczynę (brak odpowiedzi w ciągu 5 sekund, status inny niż 2xx, niezgodna wartość challenge, nieosiągalny adres URL albo adres prywatny lub wewnętrzny), a Twój obecny webhook pozostanie aktywny. Parametr webhook przekazany w settings żądania nie jest sprawdzany w ten sposób.

Które zdarzenia wyzwalają wywołanie webhooka?

Sześć typów zdarzeń może wyzwolić wywołanie webhooka, po jednym na każdy endpoint i typ wyszukiwania:

Zdarzenie	Opis
`single_search_finished`	Pojedyncze wyszukiwanie adresu e-mail zostało zakończone
`bulk_search_finished`	Masowe wyszukiwanie adresów e-mail zostało zakończone
`verification_finished`	Pojedyncza weryfikacja adresu e-mail została zakończona
`bulk_verification_finished`	Masowa weryfikacja adresów e-mail została zakończona
`single_phone_search_finished`	Pojedyncze wyszukiwanie numeru telefonu zostało zakończone
`bulk_phone_search_finished`	Masowe wyszukiwanie numerów telefonu zostało zakończone

Jak wygląda ładunek webhooka?

Ładunek webhooka zależy od endpointu oraz od tego, czy wyszukiwanie było pojedyncze, czy masowe. Pojedyncze wyszukiwania dostarczają pełny wynik bezpośrednio, natomiast masowe wyszukiwania dostarczają powiadomienie o zakończeniu, po którym wykonujesz żądanie GET.

Email Finder — pojedynczy

W przypadku pojedynczych wyszukiwań otrzymujesz pełny wynik bezpośrednio w powiadomieniu webhook. Eliminuje to potrzebę wykonywania żądania GET.

{
  "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"
    }
  }
}

Wyszukiwanie na podstawie adresu URL profilu LinkedIn

W przypadku wyszukiwania uruchomionego na podstawie adresu URL profilu LinkedIn pole result zawiera także linkedin_status i linkedin_url (wysłany przez Ciebie adres URL). Pole info jest dołączane tylko wtedy, gdy zostanie znaleziony adres e-mail: wyszukiwanie, które niczego nie znajdzie, nigdy nie ujawnia, kim jest dana osoba. credits.cost to koszt końcowy, tak jak credits_used w odpowiedzi GET, gdzie wyjaśniono również każdy linkedin_status.

{
  "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 — masowy

W przypadku masowych wyszukiwań otrzymujesz powiadomienie o zakończeniu partii. Następnie wywołaj endpoint GET /email/find/bulk z id, aby pobrać wyniki.

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

Email Verifier — pojedynczy

Pełny wynik jest dołączony bezpośrednio — żądanie GET nie jest potrzebne.

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

Email Verifier — masowy

To wyłącznie powiadomienie. Wywołaj GET /email/verify/bulk z id, aby pobrać wyniki.

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

Phone Finder — pojedynczy

Pełny wynik jest dołączony bezpośrednio — żądanie GET nie jest potrzebne.

{
  "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 — masowy

To wyłącznie powiadomienie. Wywołaj GET /phone/bulk z id, aby pobrać wyniki.

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

Czym różnią się webhooki pojedyncze i masowe?

Webhooki pojedynczych wyszukiwań zawierają kompletny wynik, więc nie jest potrzebne dodatkowe wywołanie. Webhooki masowych wyszukiwań jedynie sygnalizują, że partia jest gotowa — następnie pobierasz wyniki za pomocą odpowiadającego endpointu GET.

Typ	Pojedyncze wyszukiwania	Masowe wyszukiwania
Ładunek	Dołączony pełny wynik	Tylko powiadomienie (ID oraz kredyty, z wyjątkiem wyszukiwań numerów telefonu)
Potrzebny GET?	Nie	Tak — użyj endpointu GET z `id`

W przypadku pojedynczych wyszukiwań webhook zawiera wszystko, czego potrzebujesz. W przypadku masowych wyszukiwań webhook informuje, że partia jest gotowa — wtedy pobierasz wyniki.

Jakie są najlepsze praktyki dla endpointów webhooków?

Niezawodny endpoint webhooka odpowiada szybko, używa HTTPS i toleruje sporadyczne duplikaty. Stosuj te praktyki, aby dostarczanie było niezawodne:

Szybko zwracaj 200

Przetwarzaj ładunki webhooków asynchronicznie. Zwróć 200 natychmiast, a następnie obsłuż dane w zadaniu działającym w tle.

Używaj HTTPS

Używaj endpointu HTTPS, aby wyniki były przesyłane w formie zaszyfrowanej. Zwykłe adresy URL HTTP są akceptowane, ale niezalecane.

Obsługuj duplikaty

W rzadkich przypadkach webhooki mogą zostać dostarczone więcej niż raz. Użyj pola id, aby usuwać duplikaty.

Używaj pól niestandardowych

Przekazuj dane custom w swoich żądaniach, aby zidentyfikować, do którego rekordu należy wynik webhooka:

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

Pole custom jest zwracane w ładunku webhooka bez zmian.

Czy używać webhooków, czy odpytywania?

Używaj webhooków w produkcji, a odpytywania tylko do szybkiego prototypowania lub debugowania. Webhooki dostarczają wyniki w czasie rzeczywistym, nie zużywając Twojego limitu żądań, natomiast odpytywanie wykonuje powtarzające się wywołania GET, które wliczają się do Twoich limitów szybkości.

	Webhooki	Odpytywanie (GET)
Opóźnienie	Czas rzeczywisty	Zależy od interwału odpytywania
Wywołania API	0 (Enrow wywołuje Ciebie)	Wiele wywołań na wyszukiwanie
Wpływ na limit szybkości	Brak	Zużywa limit
Złożoność	Wymaga konfiguracji endpointu	Prostsze we wdrożeniu

Zalecamy webhooki do użytku produkcyjnego. Odpytywania używaj tylko do szybkiego prototypowania lub debugowania.

FAQ

Czy webhooki kosztują dodatkowe kredyty?

Nie. Webhooki nie zużywają dodatkowych kredytów: płacisz tylko za samo wyszukiwanie. Ładunki Email Finder i Email Verifier podają koszt w kredytach w polu credits.cost. To koszt końcowy po zwrotach: 0 dla pojedynczego wyszukiwania bez wyniku (0.25 dla wyszukiwania adresu e-mail na podstawie adresu URL profilu LinkedIn lub dla konta z nienormalnie niskim wskaźnikiem skuteczności), a dla wyszukiwania zbiorczego znalezione wiersze plus obciążone niepowodzenia. Ładunki Phone Finder nie zawierają kosztu. Zobacz Kredyty i rozliczenia, aby poznać koszty dla poszczególnych endpointów.

Co się stanie, jeśli mój endpoint nie zwróci 200?

Enrow wysyła każde powiadomienie jeden raz. Jeśli Twój serwer jest nieosiągalny lub odpowiada statusem innym niż 2xx, dostarczenie kończy się niepowodzeniem i nie jest ponawiane. Zawsze możesz pobrać wyniki, odpytując odpowiedni endpoint GET z id wyszukiwania.

Jak dopasować webhooka do pierwotnego żądania?

Użyj id z odpowiedzi wyszukiwania albo przekaż obiekt custom w swoim żądaniu — jest on zwracany w ładunku webhooka bez zmian, dzięki czemu możesz przyporządkować wyniki do własnych rekordów, takich jak ID leada w CRM.

Dlaczego nie otrzymałem webhooka?

Najczęstsze przyczyny to endpoint, który nie zwraca 2xx, serwer, który przekracza limit czasu, lub adres URL, który nie jest publicznie osiągalny. Nieudane dostarczenia nie są ponawiane: pobierz wynik za pomocą odpowiedniego endpointu GET i id wyszukiwania. Aby uzyskać szersze wskazówki dotyczące rozwiązywania problemów, zobacz Obsługa błędów oraz Kody statusu.

Następne kroki

Znajdź adres e-mail

Przekaż adres URL webhooka w settings, aby wynik został dostarczony automatycznie.

Pobierz wyniki masowe

Pobierz wyniki partii po wyzwoleniu webhooka bulk_search_finished.

Uwierzytelnianie

Jak przekazać swój klucz API w nagłówku x-api-key.

Limity szybkości

Zobacz, dlaczego webhooki unikają limitu żądań zużywanego przez odpytywanie.

Pierwsze kroki

Email Finder

Email Verifier

Phone Finder

Konto

Po co używać webhooków?

Jak przebiega proces webhooka?

Jak skonfigurować webhooka?

Jak zweryfikować swój endpoint webhooka?

Które zdarzenia wyzwalają wywołanie webhooka?

Jak wygląda ładunek webhooka?

Email Finder — pojedynczy

Wyszukiwanie na podstawie adresu URL profilu LinkedIn

Email Finder — masowy

Email Verifier — pojedynczy

Email Verifier — masowy

Phone Finder — pojedynczy

Phone Finder — masowy

Czym różnią się webhooki pojedyncze i masowe?

Jakie są najlepsze praktyki dla endpointów webhooków?

Czy używać webhooków, czy odpytywania?

FAQ

Następne kroki

Znajdź adres e-mail

Pobierz wyniki masowe

Uwierzytelnianie

Limity szybkości

​Po co używać webhooków?

​Jak przebiega proces webhooka?

​Jak skonfigurować webhooka?

​Jak zweryfikować swój endpoint webhooka?

​Które zdarzenia wyzwalają wywołanie webhooka?

​Jak wygląda ładunek webhooka?

​Email Finder — pojedynczy

​Wyszukiwanie na podstawie adresu URL profilu LinkedIn

​Email Finder — masowy

​Email Verifier — pojedynczy

​Email Verifier — masowy

​Phone Finder — pojedynczy

​Phone Finder — masowy

​Czym różnią się webhooki pojedyncze i masowe?

​Jakie są najlepsze praktyki dla endpointów webhooków?

​Czy używać webhooków, czy odpytywania?

​FAQ

​Następne kroki

Znajdź adres e-mail

Pobierz wyniki masowe

Uwierzytelnianie

Limity szybkości

Po co używać webhooków?

Jak przebiega proces webhooka?

Jak skonfigurować webhooka?

Jak zweryfikować swój endpoint webhooka?

Które zdarzenia wyzwalają wywołanie webhooka?

Jak wygląda ładunek webhooka?

Email Finder — pojedynczy

Wyszukiwanie na podstawie adresu URL profilu LinkedIn

Email Finder — masowy

Email Verifier — pojedynczy

Email Verifier — masowy

Phone Finder — pojedynczy

Phone Finder — masowy

Czym różnią się webhooki pojedyncze i masowe?

Jakie są najlepsze praktyki dla endpointów webhooków?

Czy używać webhooków, czy odpytywania?

FAQ

Następne kroki