Come funzionano i webhook - Enrow API Documentation

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: configura un webhook predefinito dalla pagina delle integrazioni nella dashboard

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

Il tuo URL webhook deve essere un endpoint HTTPS valido che restituisce un codice di stato 200.

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

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",
  "credits": {
    "cost": 50
  },
  "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 + crediti)
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, accetta solo 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 sempre endpoint HTTPS. I webhook HTTP verranno rifiutati.

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. Il costo in crediti è riportato nel campo credits.cost del payload. Consulta Crediti e fatturazione per i costi per endpoint.

Cosa succede se il mio endpoint non restituisce un 200?

Il tuo URL webhook deve essere un endpoint HTTPS valido che restituisce un codice di stato 200. Se il tuo server è irraggiungibile o risponde con un altro stato, la consegna viene considerata fallita. Come ripiego, 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 URL non HTTPS, un endpoint che non restituisce 200 o un server che va in timeout. Verifica che il tuo endpoint sia pubblicamente raggiungibile tramite HTTPS. 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.

​Perché usare i webhook?

​Come funziona un flusso webhook?

​Come configuro un webhook?

​Quali eventi attivano una chiamata webhook?

​Che aspetto ha un payload webhook?

​Email Finder — Singolo

​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?

Quali eventi attivano una chiamata webhook?

Che aspetto ha un payload webhook?

Email Finder — Singolo

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