Come funzionano i webhook

Perché usare i webhook?

I webhook fanno arrivare i risultati direttamente a te, invece di richiederli ripetutamente. Anziché interrogare un endpoint GET finché una ricerca non è terminata, Enrow invia ogni risultato al tuo server nel momento in cui è pronto, risparmiando richieste, riducendo la latenza e mantenendo il codice semplice. Smetti di sprecare richieste: lascia che siano i risultati a raggiungerti. Poiché ogni endpoint di Enrow è asincrono, i webhook sono il metodo consigliato per ricevere i risultati di Email Finder, Email Verifier e Phone Finder. I webhook inoltre aggirano completamente i limiti di frequenza, poiché è Enrow a chiamare te e non il contrario.

Come funziona un flusso webhook?

Un flusso webhook trasforma una singola richiesta di ricerca in una consegna automatica. Indichi a Enrow dove inviare i risultati ed Enrow si occupa del resto:

Invii una richiesta di ricerca in POST con un URL webhook nelle settings
Enrow restituisce immediatamente un ID di ricerca
Enrow elabora la ricerca in background
Al completamento, Enrow invia i risultati in POST al tuo URL webhook

Come configuro un webhook?

Puoi registrare un webhook in due modi, a seconda che lo desideri per una singola ricerca o per ogni ricerca:

Per richiesta: includi un URL webhook nell’oggetto settings di qualsiasi chiamata API
Globale: imposta un webhook predefinito nella pagina API della dashboard. Enrow controlla l’URL quando lo salvi: consulta Come verifico il mio endpoint webhook?

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

Quando una richiesta include un proprio webhook, cosa succede a quello predefinito dipende dall’endpoint:

Email Finder: Enrow notifica entrambi gli URL (una sola volta se coincidono)
Phone Finder ed Email Verifier: l’URL indicato nella richiesta sostituisce quello predefinito

Il tuo endpoint webhook deve essere raggiungibile pubblicamente e restituire un codice di stato 2xx. Usa HTTPS: gli URL in semplice HTTP sono accettati, ma sconsigliati. Enrow invia ogni notifica una sola volta e non ritenta una consegna fallita: puoi sempre ripiegare sull’endpoint GET corrispondente.

Come verifico il mio endpoint webhook?

Quando salvi un nuovo URL webhook predefinito nella pagina API, Enrow gli invia prima una richiesta di verifica una tantum per confermare che l’endpoint è sotto il tuo controllo. L’URL viene salvato solo se il tuo endpoint risponde correttamente a questa richiesta. Enrow invia una richiesta POST con questo corpo JSON:

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

Il tuo endpoint deve rispondere entro 5 secondi con un codice di stato 2xx e rimandare lo stesso valore challenge, come corpo grezzo della risposta oppure in JSON:

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

Ad esempio, con Node.js ed 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
});

Se la verifica non va a buon fine, l’app ne mostra il motivo (nessuna risposta entro 5 secondi, uno stato diverso da 2xx, un challenge che non corrisponde, un URL irraggiungibile oppure un indirizzo privato o interno) e il tuo webhook attuale resta attivo. Un webhook passato nelle settings di una richiesta non viene verificato in questo modo.

Quali eventi attivano una chiamata webhook?

Sei tipi di eventi possono attivare una chiamata webhook, uno per ogni endpoint e tipo di ricerca:

Evento	Descrizione
`single_search_finished`	Una singola ricerca email è terminata
`bulk_search_finished`	Una ricerca email in blocco è terminata
`verification_finished`	Una singola verifica email è terminata
`bulk_verification_finished`	Una verifica email in blocco è terminata
`single_phone_search_finished`	Una singola ricerca telefonica è terminata
`bulk_phone_search_finished`	Una ricerca telefonica in blocco è terminata

Che aspetto ha un payload webhook?

Il payload del webhook dipende dall’endpoint e dal fatto che la ricerca sia singola o in blocco. Le ricerche singole consegnano direttamente il risultato completo, mentre le ricerche in blocco consegnano una notifica di completamento a cui rispondi con una richiesta GET.

Email Finder — Singolo

Per le ricerche singole, ricevi il risultato completo direttamente nella notifica webhook. Questo elimina la necessità di eseguire una richiesta 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"
    }
  }
}

Ricerca a partire da un URL di profilo LinkedIn

Per una ricerca avviata a partire dall’URL di un profilo LinkedIn, result contiene anche linkedin_status e linkedin_url (l’URL che hai inviato). info è incluso solo se viene trovata un’email: una ricerca che non trova nulla non rivela mai chi è la persona. credits.cost è il costo finale, come credits_used nella risposta GET, che spiega anche ogni 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 — In blocco

Per le ricerche in blocco, ricevi una notifica che il batch è terminato. Poi chiama l’endpoint GET /email/find/bulk con l’id per recuperare i risultati.

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

Email Verifier — Singolo

Il risultato completo è incluso direttamente: nessuna richiesta GET necessaria.

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

Email Verifier — In blocco

Questa è solo una notifica. Chiama GET /email/verify/bulk con l’id per recuperare i risultati.

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

Phone Finder — Singolo

Il risultato completo è incluso direttamente: nessuna richiesta GET necessaria.

{
  "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 — In blocco

Questa è solo una notifica. Chiama GET /phone/bulk con l’id per recuperare i risultati.

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

In cosa differiscono i webhook singoli e in blocco?

I webhook delle ricerche singole contengono il risultato completo, quindi non è necessaria alcuna chiamata aggiuntiva. I webhook delle ricerche in blocco segnalano solo che il batch è terminato: a quel punto recuperi i risultati con l’endpoint GET corrispondente.

Tipo	Ricerche singole	Ricerche in blocco
Payload	Risultato completo incluso	Solo notifica (ID, più i crediti tranne per le ricerche telefoniche)
GET necessario?	No	Sì — usa l’endpoint GET con l’`id`

Per le ricerche singole, il webhook contiene tutto ciò di cui hai bisogno. Per le ricerche in blocco, il webhook ti informa che il batch è terminato: poi recuperi i risultati.

Quali sono le best practice per gli endpoint webhook?

Un endpoint webhook affidabile risponde rapidamente, usa HTTPS e tollera l’occasionale duplicato. Segui queste pratiche per mantenere consegne affidabili:

Restituisci 200 rapidamente

Elabora i payload dei webhook in modo asincrono. Restituisci immediatamente un 200, poi gestisci i dati in un job in background.

Usa HTTPS

Usa un endpoint HTTPS, così i risultati viaggiano cifrati. Gli URL in semplice HTTP sono accettati, ma sconsigliati.

Gestisci i duplicati

In rari casi, i webhook possono essere recapitati più di una volta. Usa il campo id per deduplicare.

Usa i campi personalizzati

Passa i dati custom nelle tue richieste per identificare a quale record appartiene il risultato di un webhook:

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

Il campo custom viene restituito così com’è nel payload del webhook.

Conviene usare i webhook o il polling?

Usa i webhook in produzione e il polling solo per prototipazione rapida o debug. I webhook consegnano i risultati in tempo reale senza consumare la tua quota di richieste, mentre il polling effettua chiamate GET ripetute che incidono sui tuoi limiti di frequenza.

	Webhook	Polling (GET)
Latenza	Tempo reale	Dipende dall’intervallo di polling
Chiamate API	0 (è Enrow a chiamarti)	Più chiamate per ricerca
Impatto sul rate limit	Nessuno	Consuma la quota
Complessità	Richiede la configurazione di un endpoint	Più semplice da implementare

Consigliamo i webhook per l’uso in produzione. Usa il polling solo per la prototipazione rapida o il debug.

FAQ

I webhook costano crediti aggiuntivi?

No. I webhook non consumano crediti aggiuntivi: paghi solo per la ricerca stessa. I payload di Email Finder ed Email Verifier riportano il costo in crediti nel campo credits.cost. È il costo finale, al netto dei rimborsi: 0 per una ricerca singola senza risultato (0.25 per una ricerca email a partire dall’URL di un profilo LinkedIn o per un account con un tasso di successo anormalmente basso) e, per una ricerca in blocco, le righe trovate più i fallimenti addebitati. I payload di Phone Finder non includono il costo. Consulta Crediti e fatturazione per i costi per endpoint.

Cosa succede se il mio endpoint non restituisce un 200?

Enrow invia ogni notifica una sola volta. Se il tuo server è irraggiungibile o risponde con uno stato diverso da 2xx, la consegna fallisce e non viene ritentata. Puoi sempre recuperare i risultati interrogando il relativo endpoint GET con l’id della ricerca.

Come associo un webhook alla richiesta originale?

Usa l’id della risposta di ricerca, oppure passa un oggetto custom nella tua richiesta: viene restituito così com’è nel payload del webhook, così puoi ricollegare i risultati ai tuoi record, come un ID lead del CRM.

Perché non ho ricevuto un webhook?

Le cause più comuni sono un endpoint che non restituisce 2xx, un server che va in timeout o un URL non raggiungibile pubblicamente. Le consegne fallite non vengono ritentate: recupera il risultato con l’endpoint GET corrispondente e l’id della ricerca. Per una risoluzione dei problemi più approfondita, consulta Gestione degli errori e Codici di stato.

Prossimi passi

Trova un'email

Passa un URL webhook nelle settings per ricevere il risultato automaticamente.

Recupera risultati in blocco

Recupera i risultati del batch dopo che si attiva un webhook bulk_search_finished.

Autenticazione

Come passare la tua chiave API nell’header x-api-key.

Limiti di frequenza

Scopri perché i webhook evitano la quota di richieste consumata dal polling.

Per iniziare

Email Finder

Email Verifier

Phone Finder

Account

Perché usare i webhook?

Come funziona un flusso webhook?

Come configuro un webhook?

Come verifico il mio endpoint webhook?

Quali eventi attivano una chiamata webhook?

Che aspetto ha un payload webhook?

Email Finder — Singolo

Ricerca a partire da un URL di profilo LinkedIn

Email Finder — In blocco

Email Verifier — Singolo

Email Verifier — In blocco

Phone Finder — Singolo

Phone Finder — In blocco

In cosa differiscono i webhook singoli e in blocco?

Quali sono le best practice per gli endpoint webhook?

Conviene usare i webhook o il polling?

FAQ

Prossimi passi

Trova un'email

Recupera risultati in blocco

Autenticazione

Limiti di frequenza

​Perché usare i webhook?

​Come funziona un flusso webhook?

​Come configuro un webhook?

​Come verifico il mio endpoint webhook?

​Quali eventi attivano una chiamata webhook?

​Che aspetto ha un payload webhook?

​Email Finder — Singolo

​Ricerca a partire da un URL di profilo LinkedIn

​Email Finder — In blocco

​Email Verifier — Singolo

​Email Verifier — In blocco

​Phone Finder — Singolo

​Phone Finder — In blocco

​In cosa differiscono i webhook singoli e in blocco?

​Quali sono le best practice per gli endpoint webhook?

​Conviene usare i webhook o il polling?

​FAQ

​Prossimi passi

Trova un'email

Recupera risultati in blocco

Autenticazione

Limiti di frequenza

Perché usare i webhook?

Come funziona un flusso webhook?

Come configuro un webhook?

Come verifico il mio endpoint webhook?

Quali eventi attivano una chiamata webhook?

Che aspetto ha un payload webhook?

Email Finder — Singolo

Ricerca a partire da un URL di profilo LinkedIn

Email Finder — In blocco

Email Verifier — Singolo

Email Verifier — In blocco

Phone Finder — Singolo

Phone Finder — In blocco

In cosa differiscono i webhook singoli e in blocco?

Quali sono le best practice per gli endpoint webhook?

Conviene usare i webhook o il polling?

FAQ

Prossimi passi