Panoramica dei webhook

Sursa registra un evento per ogni modifica importante: una scheda viene pubblicata, verificata o archiviata, una comunicazione viene letta, una domanda resta senza risposta. Puoi ricevere gli eventi in due modi e usarli entrambi insieme:

Entrambi trasportano gli stessi eventi con gli stessi ID. Ogni evento resta nel feed per 30 giorni, che un webhook lo abbia sottoscritto o no.

L’evento

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

data contiene solo ciò che qualsiasi lettore dell’oggetto potrebbe vedere tramite l’API. Non contiene mai elenchi di accesso, permessi di altre persone o campi nascosti. I motivi negli eventi sono brevi codici neutri come no_hits, restricted o index_failed.

Tipi di evento

Gli eventi coprono queste aree:

L’elenco completo, con lo schema e un esempio di ogni evento, si trova nel catalogo degli eventi del riferimento API. GET /v1/webhooks/catalog restituisce i tipi disponibili nella tua installazione.

Nel tempo si aggiungono nuovi tipi di evento e gli eventi esistenti acquisiscono nuovi campi. I tipi di evento non vengono mai rinominati né rimossi. Il tuo ricevitore deve ignorare i tipi e i campi che non conosce.

Chi riceve cosa

Un webhook riceve un evento solo se l’oggetto dell’evento è visibile al webhook, come lo sarebbe per una chiave API: in base al suo ruolo, al suo profilo dati e alle sue raccolte. Un webhook limitato alla raccolta support non riceve mai eventi sulle schede di finance. Gli eventi su persone, chiavi, fonti, importazioni, job, esportazioni, fatturazione, applicazioni e sui webhook stessi vanno solo ai webhook con il ruolo admin.

Entro questi limiti, ogni webhook sceglie i propri eventi:

• per tipo, con maschere: card.* per ogni evento delle schede, * per ogni evento;
• per raccolta e per tag, per gli eventi delle schede.

La modalità del payload di un webhook è full (l’evento con data, il valore predefinito) oppure thin (l’evento senza data: il tuo ricevitore legge l’oggetto tramite l’API con la propria chiave e ne vede sempre lo stato attuale).

La consegna in breve

• Un POST HTTPS con l’evento in JSON, firmato con il segreto del webhook in due formati: Standard Webhooks (webhook-signature) e il precedente X-KB-Signature.
• Qualsiasi risposta 2xx entro 10 secondi è un successo.
• Una consegna non riuscita viene ritentata per quasi tre giorni con pause sempre più lunghe. Retry-After in una risposta 429 o 503 viene rispettato; 410 disattiva il webhook; 10 errori consecutivi lo mettono in pausa finché non viene ripreso.
• Le consegne a uno stesso webhook vengono inviate rigorosamente in ordine. Un webhook lento non ritarda gli altri.
• Lo stesso evento può arrivare più di una volta: scarta i duplicati in base a webhook-id.

Ricevere i webhook illustra un ricevitore completo, con la verifica delle firme in Node.js, Python e Go.

Gestire i webhook

La gestione dei webhook richiede una chiave con il ruolo admin e l’ambito webhooks:manage, oppure un amministratore nell’interfaccia di amministrazione. Un’organizzazione può avere fino a 20 webhook. I webhook fanno parte del piano dell’organizzazione; senza di essi, questi endpoint rispondono 403 con il codice webhooks.feature_disabled.