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