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
| Evento | Sullo schermo | Inviato quando | content tiene |
|---|---|---|---|
add_post | Il post è stato creato. | Qualcuno pubblica informazioni riguardo a un caso specifico nel feed relativo a quel caso. | new: Il testo della posta. |
modify_post | Il post è stato modificato. | Il testo di una pubblicazione viene modificato. | new: Il nuovo testo |
delete_post | Il post è stato eliminato. | La posta è stata eliminata. | old: il suo testo |
add_post_comment | Il commento viene creato. | Qualcuno commenta un post. | new: Il testo del commento |
modify_post_comment | Il commento postato è stato modificato. | Il testo del commento è stato modificato. | new: Il nuovo testo |
delete_post_comment | Il commento è stato eliminato. | Un commento è stato eliminato. | old: il suo testo |
add_post_media | I post sui social media vengono creati in modo automatico. | Un file viene aggiunto a una posta. | new: un collegamento al file. |
delete_post_media | Il 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_media | Il mezzo per lasciare dei commenti viene creato. | Un file viene aggiunto a un commento. | new: un collegamento al file. |
delete_post_comment_media | Il 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_postLa 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 tipoadd_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
whenper 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}
}
| Campo | Cosa contiene |
|---|---|
what.trigger.name | L’evento, come indicato nella tabella sopra. |
what.content.new o what.content.old | Il testo, o un collegamento al file |
who.user_id | Chi ha scritto il post o il commento? E se qualcun altro lo ha modificato o eliminato… |
who.post.post_id | Il post, riguardante gli eventi accaduti in passato. |
who.comment.comment_id | Il commento, riguardo agli eventi legati ai commenti stessi. |
who.comment.post_id | Il post in cui il commento è stato pubblicato. |
who.case.case_id | Il caso, determinato dall’ID utilizzato dall’API. |
who.case.case_ref_id | L’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_id | Il 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_id | Il tuo centro di gravità/il luogo in cui ti trovi il cuore. |
when.datetime.datetime | Quando è successo, nel fuso orario UTC. |
Gli altri campi sono destinati all’uso proprio del hub stesso; potete ignorarli.