Centro de ayudaIntegraciones

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

EventoEn pantallaEnviado cuandocontent contiene
add_postEl mensaje se ha creado.Alguien publica información sobre un caso en el “Feed” del mismo.new: El texto de la publicación.
modify_postEl mensaje ha sido modificado.El texto de la publicación ha sido modificado.new: El nuevo texto
delete_postEl mensaje fue eliminado.La publicación se ha eliminado.old: su texto
add_post_commentEl comentario se ha creado.Alguien comenta sobre una publicación.new: El texto del comentario.
modify_post_commentEl comentario ha sido modificado.El texto de la opinión ha sido modificado.new: El nuevo texto
delete_post_commentEl comentario fue eliminado.Un comentario fue eliminado.old: su texto
add_post_mediaLos 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_mediaEl 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_mediaEl 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_mediaEl 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_post relacionado 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 uno add_post_media por 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 when para 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}
}
CampoLo que contiene
what.trigger.nameEl evento, según lo indicado en la tabla anterior.
what.content.new o what.content.oldEl 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_idEl post, sobre eventos pasados.
who.comment.comment_idEl comentario, sobre los eventos relacionados con los comentarios.
who.comment.post_idEl mensaje en el que se publica el comentario
who.case.case_idEl caso, según lo indicado por la API.
who.case.case_ref_idLa 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_idEl 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_idTu centro de operaciones.
when.datetime.datetimeCuando eso ocurrió, en UTC.

Los demás campos son para uso exclusivo del propio centro de datos. No los tome en consideración.

Artículos relacionados

Configura un webhook para la actividad del feed.Envía un mensaje a tu propio sistema cada vez que se agregue, modifique o elimine una publicación, comentario o archivo adjunto en el feed.Integraciones · 10 minSolucionar un webhook que dejó de enviarPor qué un webhook se detiene después de dos entregas fallidas o cuando está inactivo, y cómo al guardarlo de nuevo se vuelve a activar.Integraciones