Vai al contenuto principale
Header

​
Panoramica

I Webhooks in Twenty completano l’API abilitando notifiche in tempo reale alle tue applicazioni quando accadono determinati eventi nel tuo CRM. Invece di interrogare continuamente l’API per i cambiamenti, puoi impostare i webhooks per far sì che Twenty invi dati al tuo sistema ogni volta che si verificano eventi specifici (ad esempio, quando viene creato un nuovo record o aggiornato un record esistente). Questo aiuta a mantenere i sistemi esterni sincronizzati con Twenty in modo istantaneo ed efficiente. Con i webhooks, Twenty invierà una richiesta HTTP POST a un URL da te specificato, contenente i dettagli dell’evento. Puoi quindi gestire tali dati nella tua applicazione (ad esempio, per aggiornare il tuo database esterno, attivare flussi di lavoro o inviare avvisi).

​
Impostare un Webhook

Per creare un webhook in Twenty, usa le impostazioni API e Webhooks nella tua app Twenty:
  1. Naviga verso Impostazioni: Nella tua applicazione Twenty, vai a Impostazioni → APIs & Webhooks.
  2. Crea un Webhook: Sotto Webhooks clicca su + Crea webhook.
  3. Inserisci l’URL: Fornisci l’URL di endpoint sul tuo server dove desideri che Twenty invii richieste webhook. Questo deve essere un URL pubblicamente accessibile che possa gestire richieste POST.
  4. Salva: Clicca su Salva per creare il webhook. Il nuovo webhook sarà attivo immediatamente.
Puoi creare più webhooks se hai bisogno di inviare diversi eventi a endpoint diversi. Ogni webhook è essenzialmente un abbonamento per tutti gli eventi rilevanti (al momento, Twenty invia tutti i tipi di eventi all’URL dato; la filtrazione di tipi specifici di eventi potrebbe essere configurabile nell’interfaccia utente). Se dovessi mai aver bisogno di rimuovere un webhook, puoi eliminarlo dalla stessa pagina delle impostazioni (seleziona il webhook e scegli elimina).

​
Eventi e Payloads

Una volta impostato un webhook, Twenty invierà una richiesta HTTP POST all’URL specificato ogni volta che un evento di trigger si verifica nei tuoi dati CRM. Gli eventi comuni che attivano i webhooks includono:
  • Record Creato: ad esempio, viene aggiunta una nuova persona (person.created), viene creata una nuova azienda (company.created), viene creata una nota (note.created), ecc.
  • Record Aggiornato: ad esempio, vengono aggiornate le informazioni di una persona esistente (person.updated), viene modificato un record aziendale (company.updated), ecc.
  • Record Eliminato: ad esempio, una persona o un’azienda viene eliminata (person.deleted, company.deleted).
  • Altri Eventi: Se applicabile, altri eventi di oggetto o trigger personalizzati (ad esempio, se i task o altri oggetti vengono aggiornati, verrebbero utilizzati tipi di eventi simili come task.created, note.updated, ecc.).
La richiesta POST del webhook contiene un payload JSON nel suo corpo. Il payload generalmente includerà almeno due cose: il tipo di evento e i dati relativi a quell’evento (spesso il record che è stato creato/aggiornato). Ad esempio, un webhook per una persona appena creata potrebbe inviare un payload come: 
{
  "event": "person.created",
  "data": {
    "id": "abc12345",
    "firstName": "Alice",
    "lastName": "Doe",
    "email": "alice@example.com",
    "createdAt": "2025-02-10T15:30:45Z",
    "createdBy": "user_123"
  },
  "timestamp": "2025-02-10T15:30:50Z"
}
In questo esempio:
  • "event" specifica ciò che è avvenuto (person.created).
  • "data" contiene i dettagli del nuovo record (le stesse informazioni che otterresti se richiedessi quella persona tramite l’API).
  • "timestamp" indica quando l’evento è avvenuto (in UTC).
Il tuo endpoint dovrebbe essere preparato per ricevere tali dati JSON tramite POST. Tipicamente, elaborerai il JSON, guarderai il tipo di "event" per capire cosa è successo e quindi utilizzerai i "data" di conseguenza (ad esempio, creare un nuovo contatto nel tuo sistema o aggiornare uno esistente). Nota: È importante rispondere con uno stato HTTP 2xx dal tuo endpoint webhook per riconoscere la ricezione avvenuta con successo. Se il mittente del webhook Twenty non riceve una risposta 2xx, potrebbe considerare la consegna fallita. (In futuro, la logica di retry potrebbe tentare di rinviare i webhooks falliti, quindi cerca sempre di restituire un 200 OK il più rapidamente possibile dopo aver elaborato i dati.)

​
Convalida del Webhook

Per garantire la sicurezza dei tuoi endpoint webhook, Twenty include una firma nell’intestazione X-Twenty-Webhook-Signature. Questa firma è un hash HMAC SHA256 del payload della richiesta, calcolato utilizzando il tuo segreto del webhook. Per convalidare la firma, dovrai:
  1. Concatena il timestamp (dall’intestazione X-Twenty-Webhook-Timestamp), due punti e la stringa JSON del payload
  2. Calcola l’hash HMAC SHA256 usando il tuo segreto del webhook come chiave ()
  3. Confronta il digest esadecimale risultante con l’intestazione della firma
Ecco un esempio in Node.js: 
const crypto = require("crypto");
const timestamp = "1735066639761";
const payload = JSON.stringify({...});
const secret = "your-secret";
const stringToSign = `${timestamp}:${JSON.stringify(payload)}`;
const signature = crypto.createHmac("sha256", secret)
  .update(stringToSign)
  .digest("hex");