Webhooks

Twenty envía un HTTP POST a tu URL cada vez que se crea, actualiza o elimina un registro. Todos los tipos de objetos están cubiertos, incluidos los objetos personalizados.

Crear un webhook

Ve a Configuración → APIs y Webhooks → Webhooks
Haz clic en + Crear webhook
Introduce la URL de tu webhook (debe ser públicamente accesible)
Haz clic en Guardar

El webhook se activa de inmediato y comienza a enviar notificaciones.

Gestionar webhooks

Editar: Haz clic en el webhook → Actualizar la URL → Guardar Eliminar: Haz clic en el webhook → Eliminar → Confirmar

Eventos

Twenty envía webhooks para estos tipos de eventos:

Evento	Ejemplo
Se crea un registro	`person.created`, `company.created`, `note.created`
Se actualiza un registro	`person.updated`, `company.updated`, `opportunity.updated`
Se elimina un registro	`person.deleted`, `company.deleted`

Todos los tipos de eventos se envían a la URL de tu webhook. Es posible que se agregue el filtrado de eventos en versiones futuras.

Formato de la carga útil

Cada webhook envía una solicitud HTTP POST con un cuerpo JSON:

{
  "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"
}

Campo	Descripción
`event`	Qué ocurrió (p. ej., `person.created`)
`data`	El registro completo que se creó/actualizó/eliminó
`timestamp`	Cuándo ocurrió el evento (UTC)

Responde con un estado HTTP 2xx (200-299) para confirmar la recepción. Las respuestas que no sean 2xx se registran como errores de entrega.

Validación de webhook

Twenty firma cada solicitud de webhook por seguridad. Valida las firmas para garantizar que las solicitudes sean auténticas.

Encabezados

Encabezado	Descripción
`X-Twenty-Webhook-Signature`	Firma HMAC SHA256
`X-Twenty-Webhook-Timestamp`	Marca de tiempo de la solicitud

Pasos de validación

Obtén la marca de tiempo de X-Twenty-Webhook-Timestamp
Crea la cadena: {timestamp}:{JSON payload}
Calcula HMAC SHA256 usando tu secreto de webhook
Compara con X-Twenty-Webhook-Signature

Ejemplo (Node.js)

const crypto = require("crypto");

const timestamp = req.headers["x-twenty-webhook-timestamp"];
const payload = JSON.stringify(req.body);
const secret = "your-webhook-secret";

const stringToSign = `${timestamp}:${payload}`;
const expectedSignature = crypto
  .createHmac("sha256", secret)
  .update(stringToSign)
  .digest("hex");

const receivedSignature = req.headers["x-twenty-webhook-signature"];
const isValid = crypto.timingSafeEqual(
  Buffer.from(expectedSignature, "hex"),
  Buffer.from(receivedSignature, "hex")
);

Webhooks vs flujos de trabajo

Método	Dirección	Caso de uso
Webhooks	SALIDA	Notificar automáticamente a los sistemas externos cualquier cambio en un registro
Flujo de trabajo + solicitud HTTP	SALIDA	Enviar datos con lógica personalizada (filtros, transformaciones)
Disparador de webhook de flujo de trabajo	ENTRADA	Recibir datos en Twenty desde sistemas externos

Para recibir datos externos, consulta Configurar un disparador de webhook.

Resumen

Aplicaciones

API

Autoalojamiento

Contribuir

Crear un webhook

Gestionar webhooks

Eventos

Formato de la carga útil

Validación de webhook

Encabezados

Pasos de validación

Ejemplo (Node.js)

Webhooks vs flujos de trabajo

​Crear un webhook

​Gestionar webhooks

​Eventos

​Formato de la carga útil

​Validación de webhook

​Encabezados

​Pasos de validación

​Ejemplo (Node.js)

​Webhooks vs flujos de trabajo

Crear un webhook

Gestionar webhooks

Eventos

Formato de la carga útil

Validación de webhook

Encabezados

Pasos de validación

Ejemplo (Node.js)

Webhooks vs flujos de trabajo