Saltar al contenido principal
Header

​
Resumen

Los Webhooks en Twenty complementan la API permitiendo notificaciones en tiempo real a tus propias aplicaciones cuando ciertos eventos ocurren en tu CRM. En lugar de sondear continuamente la API en busca de cambios, puedes configurar webhooks para que Twenty envíe datos a tu sistema siempre que ocurran eventos específicos (por ejemplo, cuando se crea un nuevo registro o se actualiza un registro existente). Esto ayuda a mantener los sistemas externos sincronizados con Twenty de forma instantánea y eficiente. Con webhooks, Twenty enviará una solicitud HTTP POST a una URL que especifiques, conteniendo detalles sobre el evento. Luego puedes manejar esos datos en tu aplicación (por ejemplo, para actualizar tu base de datos externa, activar flujos de trabajo o enviar alertas).

​
Configuración de un Webhook

Para crear un webhook en Twenty, usa la configuración de APIs & Webhooks en tu aplicación Twenty:
  1. Navega a Configuración: En tu aplicación Twenty, ve a Configuración → APIs & Webhooks.
  2. Crea un Webhook: Bajo Webhooks haz clic en + Crear webhook.
  3. Introduce la URL: Proporciona el endpoint URL en tu servidor donde deseas que Twenty envíe solicitudes de webhook. Esta debe ser una URL accesible públicamente que pueda manejar solicitudes POST.
  4. Guardar: Haz clic en Guardar para crear el webhook. El nuevo webhook estará activo de inmediato.
Puedes crear múltiples webhooks si necesitas enviar diferentes eventos a diferentes endpoints. Cada webhook es esencialmente una suscripción para todos los eventos relevantes (en este momento, Twenty envía todos los tipos de eventos a la URL proporcionada; filtrar tipos de eventos específicos puede ser configurable en la interfaz de usuario). Si alguna vez necesitas eliminar un webhook, puedes eliminarlo desde la misma página de configuración (selecciona el webhook y elige eliminar).

​
Eventos y Cargas Útiles

Una vez que se configura un webhook, Twenty enviará una solicitud HTTP POST a tu URL especificada cada vez que ocurra un evento desencadenante en tus datos de CRM. Los eventos comunes que activan webhooks incluyen:
  • Registro Creado: por ejemplo, se agrega una nueva persona (person.created), se crea una nueva empresa (company.created), se crea una nota (note.created), etc.
  • Registro Actualizado: por ejemplo, se actualiza la información de una persona existente (person.updated), se edita un registro de empresa (company.updated), etc.
  • Registro Eliminado: por ejemplo, se elimina una persona o empresa (person.deleted, company.deleted).
  • Otros Eventos: Si corresponde, otros eventos de objetos o desencadenantes personalizados (por ejemplo, si se actualizan tareas u otros objetos, se usarían tipos de eventos similares como task.created, note.updated, etc.).
La solicitud POST del webhook contiene una carga útil en JSON en su cuerpo. La carga útil generalmente incluirá al menos dos cosas: el tipo de evento y los datos relacionados con ese evento (a menudo el registro que fue creado/actualizado). Por ejemplo, un webhook para una persona recién creada podría enviar una carga útil como: 
{
  "event": "person.created",
  "data": {
    "id": "abc12345",
    "firstName": "Alice",
    "lastName": "Doe",
    "email": "alice@example.com",
    "createdAt": "2025-02-10T15:30:45Z",
    "createdBy": "user_123"
  },
  "timestamp": "2025-02-10T15:30:50Z"
}
En este ejemplo:
  • "evento" especifica lo que sucedió (person.created).
  • "datos" contiene los detalles del nuevo registro (la misma información que obtendrías si solicitases esa persona a través de la API).
  • "marca de tiempo" es cuando ocurrió el evento (en UTC).
Tu endpoint debe estar preparado para recibir dichos datos JSON a través de POST. Típicamente, analizarás el JSON, observarás el tipo de "evento" para entender lo que ocurrió, y luego usarás los "datos" en consecuencia (por ejemplo, crear un nuevo contacto en tu sistema o actualizar uno existente). Nota: Es importante responder con un estado HTTP 2xx desde tu endpoint de webhook para reconocer la recepción exitosa. Si el remitente del webhook de Twenty no recibe una respuesta 2xx, puede considerar que la entrega falló. (En el futuro, la lógica de reintento podría intentar reenviar webhooks fallidos, por lo que siempre debes esforzarte por devolver un 200 OK tan rápidamente como sea posible después de procesar los datos).

​
Validación de Webhook

Para garantizar la seguridad de tus endpoints de webhook, Twenty incluye una firma en el encabezado X-Twenty-Webhook-Signature. Esta firma es un hash HMAC SHA256 del cargamento de la solicitud, calculado usando tu secreto de webhook. Para validar la firma, necesitarás:
  1. Concatenar la marca de tiempo (del encabezado X-Twenty-Webhook-Timestamp), un dos puntos, y la cadena JSON de la carga útil
  2. Calcular el hash HMAC SHA256 usando tu secreto de webhook como clave ()
  3. Comparar el resumen hexadecimal resultante con el encabezado de la firma
Aquí hay un ejemplo en Node.js: 
const crypto = require("crypto");
const timestamp = "1735066639761";
const payload = JSON.stringify({...});
const secret = "your-secret";
const stringToSign = `${timestamp}:${JSON.stringify(payload)}`;
const signature = crypto.createHmac("sha256", secret)
  .update(stringToSign)
  .digest("hex");