Para: Administradores
Consulta los eventos y cargas útiles de los webhooks.
Qué envía cada uno de los diez eventos de la fuente, cómo se cifra el mensaje y cómo descifrarlo con su clave secreta.
En este artículo4 secciones
Esta página enumera los eventos que envía un webhookWebhook Una dirección que le proporcionas al hub para que pueda enviar un mensaje a tus propios sistemas cada vez que cambie una publicación o comentario en el feed., cómo llegan cada mensaje y qué contienen después de ser decodificados.
Eventos
| Evento | En pantalla | Enviado cuando | content contiene |
|---|---|---|---|
add_post | El mensaje se ha creado. | Alguien publica información sobre un caso en el “Feed” del mismo. | new: El texto de la publicación. |
modify_post | El mensaje ha sido modificado. | El texto de la publicación ha sido modificado. | new: El nuevo texto |
delete_post | El mensaje fue eliminado. | La publicación se ha eliminado. | old: su texto |
add_post_comment | El comentario se ha creado. | Alguien comenta sobre una publicación. | new: El texto del comentario. |
modify_post_comment | El comentario ha sido modificado. | El texto de la opinión ha sido modificado. | new: El nuevo texto |
delete_post_comment | El comentario fue eliminado. | Un comentario fue eliminado. | old: su texto |
add_post_media | Los medios de comunicación se crean de esta manera. | Un archivo se agrega a una publicación. | new: un enlace hacia el archivo. |
delete_post_media | El contenido del post se ha eliminado. | Un archivo se elimina de una publicación. | old: Un enlace al archivo que se eliminó. |
add_post_comment_media | El medio para dejar comentarios se crea de esta manera. | Un archivo se agrega a un comentario. | new: un enlace hacia el archivo. |
delete_post_comment_media | El medio de publicación para dejar comentarios se ha eliminado. | Un archivo se elimina de un comentario. | old: Un enlace al archivo que se eliminó. |
- En cada caso que se envía a tu centro de manejo, sea quien sea el responsable de realizar el cambio: el personal del centro, un cliente, el Asistente VirtualAsistente virtual Un miembro del equipo automatizado que publica mensajes de bienvenida, registros de asistencia y actualizaciones de la empresa; sus publicaciones llevan una insignia de Asistente Virtual., una clave de importación o una clave de API. Los eventos relacionados con las publicaciones o los comentarios siguen apareciendo incluso después de que el autor de dichos eventos haya dejado el caso.
- Al eliminar un caso, no se envía nada, ni siquiera el mensaje
delete_postrelacionado con los contenidos que se eliminan. Una vez que el caso se ha eliminado, la API devuelve un error 404 para ese caso. - Solo las publicaciones y los comentarios sobre las publicaciones pueden generar eventos. Las notas, tareas, formularios, firmas electrónicas, así como los eventos y sus comentarios, no generan ningún tipo de evento. Lo mismo ocurre con los cambios en quién puede ver una publicación.
- Un mensaje que contiene archivos envía
add_post; además, se envían unoadd_post_mediapor cada archivo. - Un enlace de archivo funciona durante 48 horas. El archivo eliminado se borra poco después, por lo que el enlace relacionado con ese archivo puede no abrirse.
- En el texto, se menciona “
<@”, que corresponde al ID de usuario de la persona; además, se mencionan también “>” y “<@cu-4f1c2a9e8b7d60>”.
Entrega
- Cada mensaje es un envío POST al enderezo del webhook. El cuerpo del mensaje en formato JSON contiene un único campo:
payload: el mensaje en formato cifrado. - Cualquier estado inferior a 400 en el transcurso de 10 segundos se considera como entregado.
- Un envío que falla no se envía nuevamente. Si ocurre esto dos veces seguidas, el webhook deja de funcionar. Para solucionar este problema, vea Corregir el webhook que dejó de enviar los mensajes.
- Un mensaje puede llegar dos veces, o de forma incorrecta. Utilice el evento, la ID del elemento y
whenpara indicarlo.
{"payload": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFMyNTYifQ.…"}
Descifrado
payload es un JWE en formato compacto, cifrado utilizando los algoritmos RSA-OAEP y A128CBC-HS256. La clave secreta del webhook corresponde al mismo clave privada utilizada para el cifrado. Se trata de un archivo PEM que comienza con -----BEGIN PRIVATE KEY-----. Se puede utilizar el archivo descargado, o bien la clave secreta copiada completa, incluyendo las líneas de salida. Cualquier biblioteca JOSE puede descifrarlo.
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));
}
No existe una firma separada. Su hub nunca muestra la clave con la que cifra los mensajes. Por lo tanto, un mensaje que se puede descifrar utilizando su secreto proviene de su hub. Pero aquellos mensajes que han sido modificados en el camino no pueden ser descifrados. Si varios hubs envían mensajes a la misma dirección, también es necesario verificar who.host.host_id.
El mensaje
Un add_post descifrado:
{
"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 | Lo que contiene |
|---|---|
what.trigger.name | El evento, según lo indicado en la tabla anterior. |
what.content.new o what.content.old | El texto, o un enlace al archivo |
who.user_id | ¿Quién escribió ese mensaje o comentario? Incluso cuando alguien más lo modificó o eliminó. |
who.post.post_id | El post, sobre eventos pasados. |
who.comment.comment_id | El comentario, sobre los eventos relacionados con los comentarios. |
who.comment.post_id | El mensaje en el que se publica el comentario |
who.case.case_id | El caso, según lo indicado por la API. |
who.case.case_ref_id | La ID de etiquetaID de etiqueta Una etiqueta permanente que se le asigna a una caja, como por ejemplo rear-end-2026, que también se muestra como ID de referencia y se utiliza en las importaciones. del caso. |
who.role.role_id | El papel que desempeña el autor en este caso es algo como role::clients. Este valor se omite si el autor ya ha abandonado el caso. |
who.host.host_id | Tu centro de operaciones. |
when.datetime.datetime | Cuando eso ocurrió, en UTC. |
Los demás campos son para uso exclusivo del propio centro de datos. No los tome en consideración.