Come usare i webhook per sincronizzare le candidate con Slack e HubSpot

Che cosa fa davvero un webhook ATS

Un webhook è un gancio che l'ATS tira quando succede qualcosa — una candidata si applica, un test è completato, un colloquio è programmato. L'ATS invia un piccolo payload JSON a un URL che fornisci. Il tuo codice lo legge e fa qualcosa a valle: postare su Slack, creare un contatto HubSpot, aggiornare uno stage in Greenhouse, attivare uno Zap.

I webhook sono economici, push-based, e orientati agli eventi. Non fai polling. Non reimplementi il modello di dati. Reagisci.

Gli eventi che vale la pena collegare per primi

Undici eventi si attivano sulla superficie webhook di ClarityHire, ma solo pochi importano il primo giorno:

• application.submitted — nuova candidata nella pipeline. L'evento di notifica Slack.
• test.completed — la valutazione è classificata. L'evento «avvisa il recruiter».
• test.passed / test.failed — trigger per avanzamento automatico / archiviazione automatica.
• interview.scheduled e interview.completed — sincronizzazione del calendario e CRM.
• candidate.stage_changed — l'evento «comunica a HubSpot che il lead si è scaldato».
• candidate.hired — chiudi il ciclo con finanza / provisioning IT.

Collega application.submitted e candidate.stage_changed per primi. Tutto il resto può aspettare fino a quando non avrai imparato quali notifiche vuole davvero il tuo team.

Pattern 1 — Alert candidati Slack

La versione ingenua: un webhook → un URL Incoming Webhook in Slack → un messaggio semplice in #hiring. Va bene per una settimana. Fastidioso dopo, perché ogni nuovo candidato avvisa tutti.

Il pattern che regge:

1. Instrada per job. Mappa ogni posizione a un canale Slack (#hiring-backend, #hiring-design). Ricevi il webhook in una piccola funzione serverless, cerca il mapping job → canale, pubblica lì. Funzione di cinque righe.
2. Aggiornamenti in thread per candidata. Pubblica l'evento application.submitted iniziale come messaggio di primo livello. Pubblica eventi successivi (test.completed, interview.scheduled) come risposte nello stesso thread. Ora ogni canale legge come una timeline per candidata.
3. Un pulsante azionabile. Aggiungi un pulsante di azione Slack che collega al profilo della candidata nell'ATS. Non cercare di prendere la decisione effettiva in Slack; fallo dove vivono i dati.

Il motivo per mettere una piccola funzione nel mezzo (invece di usare direttamente il webhook in entrata nativo di Slack) è che puoi verificare la firma HMAC, cercare lo stato, e non esporre un URL Slack all'intera configurazione ATS della tua organizzazione.

Pattern 2 — Sincronizzazione contatti HubSpot

Il valore di HubSpot in una pipeline di recruiting è lo stesso di in una pipeline di vendite: mantenere un record di ogni persona che abbia mai interagito con la tua organizzazione, taggata per fase del ciclo di vita. I lead di recruiting sono persone che potresti ri-coinvolgere in tre anni.

1. application.submitted → creare/aggiornare contatto HubSpot. Imposta la fase del ciclo di vita a Other o una fase Candidate personalizzata. Allega la posizione di origine come proprietà.
2. candidate.hired → aggiorna il ciclo di vita a Customer/Employee. Sopprime le email di marketing ricorrenti alle persone che ora lavorano per te.
3. application.rejected → tag per riscoperta del talento. Un tag «rifiutato ma qualificato» è l'unico tag con il ROI più alto in un bridge HubSpot/ATS. Sei mesi dopo, quando avrai una richiesta simile, il tuo sourcer cercherà il tag.

Usa l'API batch di HubSpot per le scritture se sei in qualsiasi scala. Le scritture a contatto singolo vanno bene per iniziare, dolorose a 50 reqs/min.

Le insidie che ti colpiscono in produzione

• Verifica la firma HMAC su ogni request. L'URL del webhook è accessibile da internet. Se non verifichi, chiunque trovi il tuo URL può spammare il tuo canale Slack. I webhook di ClarityHire vengono forniti con un segreto di firma per endpoint — usalo.
• Rendi i gestori idempotenti. I webhook si ritentano su risposte non-2xx. Il tuo gestore vedrà lo stesso evento più di una volta. Basa le tue azioni a valle sull'ID dell'evento, non sul momento della ricezione.
• Rispondi 2xx velocemente, poi fai il lavoro. Un gestore di webhook che impiega 30 secondi per chiamare HubSpot prima di restituire 200 scadrà e verrà ritentato. Riconosci prima, accoda il lavoro, fallo in modo asincrono.
• Registra la consegna, separata dall'azione. L'ATS ti darà un log di consegna; costruisci anche il tuo. Quando qualcosa va perso, la domanda «l'ATS l'ha inviato, l'abbiamo ricevuto, abbiamo agito» ha bisogno di tre risposte separate.

Come è cablato il layer di webhook di ClarityHire

/dashboard/webhooks ti permette di registrare un endpoint per organizzazione, scegliere quali eventi sottoscrivere, impostare header personalizzati, e visualizzare il log per consegna con firma HMAC, payload, codice di risposta, e pulsante di replay. Le consegne fallite si ritentano con backoff esponenziale. Per integrazioni più leggere puoi anche instradare attraverso Zapier o usare i connettori nativi Slack + HubSpot e saltare completamente l'endpoint personalizzato.

TL;DR

Inizia con due eventi (application.submitted, candidate.stage_changed), un canale Slack per posizione, e un flusso di sincronizzazione contatti HubSpot. Verifica HMAC, rendi i gestori idempotenti, riconosci velocemente e accoda. Tutto il resto scala da quella base.