Centro assistenzaIntegrazioni

Per: Amministratori

Consulta gli eventi e i payload dei webhook.

Cosa invia ciascuno dei dieci eventi del feed, come viene crittografato il messaggio e come decrittografarlo con la tua chiave segreta.

In questo articolo4 sezioni

Questa pagina elenca gli eventi che viene inviato tramite il webhookWebhook Un indirizzo che fornisci all'hub in modo che possa inviare un messaggio ai tuoi sistemi ogni volta che un post o un commento del feed subisce delle modifiche., come ogni messaggio arriva e cosa contiene una volta decrittato.

Eventi

EventoSullo schermoInviato quandocontent tiene
add_postIl post è stato creato.Qualcuno pubblica informazioni riguardo a un caso specifico nel feed relativo a quel caso.new: Il testo della posta.
modify_postIl post è stato modificato.Il testo di una pubblicazione viene modificato.new: Il nuovo testo
delete_postIl post è stato eliminato.La posta è stata eliminata.old: il suo testo
add_post_commentIl commento viene creato.Qualcuno commenta un post.new: Il testo del commento
modify_post_commentIl commento postato è stato modificato.Il testo del commento è stato modificato.new: Il nuovo testo
delete_post_commentIl commento è stato eliminato.Un commento è stato eliminato.old: il suo testo
add_post_mediaI post sui social media vengono creati in modo automatico.Un file viene aggiunto a una posta.new: un collegamento al file.
delete_post_mediaIl post relativo a quel mezzo di comunicazione è stato eliminato.Un file viene rimosso da una posta.old: un collegamento al file eliminato.
add_post_comment_mediaIl mezzo per lasciare dei commenti viene creato.Un file viene aggiunto a un commento.new: un collegamento al file.
delete_post_comment_mediaIl messaggio di commento è stato eliminato.Un file viene rimosso da un commento.old: un collegamento al file eliminato.
  • In ogni caso, il sistema invia queste informazioni, indipendentemente da chi ha effettuato il cambiamento: il personale del servizio, un cliente, l’Assistente VirtualeAssistente virtuale Un membro automatizzato del team che pubblica messaggi di benvenuto, check-in e post di aggiornamento per l'azienda; i suoi post sono contrassegnati da un badge di Assistente Virtuale., una chiave di importazione o una chiave API. Gli eventi legati a una posta o a un commento vengono comunque inviati anche dopo che l’autore del messaggio o del commento ha lasciato il caso.
  • La cancellazione di un caso non produce alcun effetto, nemmeno nulla. delete_post La cancellazione di tali post comporta la loro eliminazione definitiva. Una volta che i post vengono cancellati, l’API restituisce il codice 404 per indicare che il contenuto non è più disponibile.
  • Solo i post e i commenti sui post possono generare eventi. Le note, le attività, i moduli, i documenti elettronici, gli eventi e i loro commenti non producono alcun effetto. Allo stesso modo, anche il cambio riguardo a chi può visualizzare un determinato post non influisce negativamente su nulla.
  • Un messaggio che contiene i file invia add_post; inoltre, per ogni file viene inviato un elemento di tipo add_post_media.
  • Il collegamento al file funziona per 48 ore. Il file, una volta rimosso, viene eliminato immediatamente. Pertanto, il collegamento presente durante un evento di eliminazione del file potrebbe non funzionare.
  • Nel testo, la menzione riguarda <@, che rappresenta l’ID dell’utente della persona in questione; inoltre, vengono indicati anche >, ad esempio <@cu-4f1c2a9e8b7d60>.

Consegna

  • Ogni messaggio rappresenta una richiesta inviata all’indirizzo del webhook. Il corpo del messaggio è costituito da un file JSON, e questo file contiene un singolo campo: payload: il messaggio crittografato.
  • Qualsiasi stato inferiore a 400 entro 10 secondi viene considerato come una consegna avvenuta.
  • Una consegna che fallisce non viene inviata di nuovo. Due fallimenti consecutivi interrompono il funzionamento del webhook. Per ulteriori informazioni, vedere Correzione del webhook che smette di inviare i messaggi.
  • Un messaggio può arrivare due volte, oppure in modo disordinato. È possibile utilizzare l’evento, l’ID dell’elemento e when per indicare questo fenomeno.
{"payload": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFMyNTYifQ.…"}

Decrittazione

payload è un JWE in forma compatta, crittografato utilizzando i metodi RSA-OAEP e A128CBC-HS256. La “secret key” relativa al webhook corrisponde alla chiave privata utilizzata per la crittografia; si tratta di un file PEM che inizia con -----BEGIN PRIVATE KEY-----. È possibile utilizzare il file scaricato, oppure la “secret key” copiata interamente, comprese le righe di spaziatura tra le righe del file. Qualsiasi libreria JOSE può decrittarlo.

Python, con jwcrypto:

import json
from jwcrypto import jwk, jwt

with open("webhook-private-key.pem", "rb") as f:
    key = jwk.JWK.from_pem(f.read())

def read_message(body):
    token = jwt.JWT(jwt=body["payload"], key=key, expected_type="JWE")
    return json.loads(token.claims)

Node.js, con jose:

import { readFileSync } from 'node:fs';
import { compactDecrypt, importPKCS8 } from 'jose';

const key = await importPKCS8(readFileSync('webhook-private-key.pem', 'utf8'), 'RSA-OAEP');

export async function readMessage(body) {
  const { plaintext } = await compactDecrypt(body.payload, key);
  return JSON.parse(new TextDecoder().decode(plaintext));
}

Non esiste una firma separata per il messaggio inviato. Il “hub” in questione non mostra mai la chiave con cui viene crittografato il messaggio; quindi, un messaggio che può essere decifrato utilizzando la propria chiave proviene effettivamente dal proprio “hub”. Inoltre, se più “hubs” inviano lo stesso messaggio allo stesso indirizzo, è necessario verificare anche who.host.host_id.

Il messaggio

Il testo decifrato è: add_post

{
  "who": {
    "user_id": "cu-4f1c2a9e8b7d60",
    "cc_owner": false,
    "post": {"post_id": "post::20261001140322_9f8e7d6c5b4a32"},
    "case": {"case_id": "cc-1a2b3c4d5e6f70", "case_ref_id": "rear-end-2026"},
    "role": {"role_id": "role::staff"},
    "host": {"host_id": "ca-7e6d5c4b3a2f10"}
  },
  "what": {
    "trigger": {"name": "add_post"},
    "content": {
      "new": "Hi Jane, your records request went out today.",
      "type": "app_add_post",
      "kwargs": {"case_id": "cc-1a2b3c4d5e6f70", "case_ref_id": "rear-end-2026"}
    }
  },
  "where": {"location": {"name": "app"}, "module": {"name": "post"}},
  "when": {"datetime": {"timezone": "utc", "datetime": "2026-10-01T14:03:22.123456+0000"}},
  "targets": {"user_ids": ["cu-4f1c2a9e8b7d60"], "cc_user_ids": [], "group_targets": false}
}
CampoCosa contiene
what.trigger.nameL’evento, come indicato nella tabella sopra.
what.content.new o what.content.oldIl testo, o un collegamento al file
who.user_idChi ha scritto il post o il commento? E se qualcun altro lo ha modificato o eliminato…
who.post.post_idIl post, riguardante gli eventi accaduti in passato.
who.comment.comment_idIl commento, riguardo agli eventi legati ai commenti stessi.
who.comment.post_idIl post in cui il commento è stato pubblicato.
who.case.case_idIl caso, determinato dall’ID utilizzato dall’API.
who.case.case_ref_idL’ID della tagID tag Un'etichetta permanente che si assegna a un caso, come ad esempio rear-end-2026, visualizzata anche come ID di riferimento e utilizzata nelle importazioni. del caso
who.role.role_idIl ruolo dell’autore nel caso in questione è indicato con role::clients. Questo valore viene omesso se l’autore ha lasciato il caso in questione.
who.host.host_idIl tuo centro di gravità/il luogo in cui ti trovi il cuore.
when.datetime.datetimeQuando è successo, nel fuso orario UTC.

Gli altri campi sono destinati all’uso proprio del hub stesso; potete ignorarli.

Articoli correlati

Configura un webhook per l'attività del feedInvia un messaggio al tuo sistema ogni volta che un post, un commento o un allegato viene aggiunto, modificato o eliminato.Integrazioni · 10 minRisolvi un webhook che ha smesso di inviarePerché un webhook si disattiva dopo due consegne fallite o quando è inattivo, e come salvarlo nuovamente lo riattiva.Integrazioni