Webhooks

Twenty envoie une requête HTTP POST vers votre URL chaque fois qu’un enregistrement est créé, mis à jour ou supprimé. Tous les types d’objets sont pris en charge, y compris les objets personnalisés.

Créer un Webhook

Allez dans Paramètres → API & Webhooks → Webhooks
Cliquez sur + Créer un webhook
Saisissez votre URL de webhook (doit être publiquement accessible)
Cliquez sur Enregistrer

Le webhook s’active immédiatement et commence à envoyer des notifications.

Gérer les Webhooks

Modifier: Cliquez sur le webhook → Mettre à jour l’URL → Enregistrer Supprimer: Cliquez sur le webhook → Supprimer → Confirmer

Événements

Twenty envoie des webhooks pour ces types d’événements :

Événement	Exemple
Enregistrement créé	`person.created`, `company.created`, `note.created`
Enregistrement mis à jour	`person.updated`, `company.updated`, `opportunity.updated`
Enregistrement supprimé	`person.deleted`, `company.deleted`

Tous les types d’événements sont envoyés à votre URL de webhook. Le filtrage des événements pourrait être ajouté dans de prochaines versions.

Format de la charge utile

Chaque webhook envoie une requête HTTP POST avec un corps 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"
}

Champ	Description
`event`	Ce qui s’est passé (par exemple, `person.created`)
`data`	L’enregistrement complet qui a été créé/mis à jour/supprimé
`timestamp`	Quand l’événement s’est produit (UTC)

Répondez avec un statut HTTP 2xx (200-299) pour accuser réception. Les réponses non 2xx sont consignées comme des échecs de livraison.

Validation des Webhooks

Twenty signe chaque requête de webhook pour des raisons de sécurité. Validez les signatures pour garantir l’authenticité des requêtes.

En-têtes

En-tête	Description
`X-Twenty-Webhook-Signature`	Signature HMAC SHA256
`X-Twenty-Webhook-Timestamp`	Horodatage de la requête

Étapes de validation

Récupérez l’horodatage depuis X-Twenty-Webhook-Timestamp
Créez la chaîne : {timestamp}:{JSON payload}
Calculez le HMAC SHA256 en utilisant votre secret de webhook
Comparez avec X-Twenty-Webhook-Signature

Exemple (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 Workflows

Méthode	Direction	Cas d’utilisation
Webhooks	SORTIE	Notifier automatiquement les systèmes externes de toute modification d’enregistrement
Workflow + requête HTTP	SORTIE	Envoyer des données avec une logique personnalisée (filtres, transformations)
Déclencheur de webhook de workflow	ENTRÉE	Recevoir des données dans Twenty depuis des systèmes externes

Pour recevoir des données externes, voir Configurer un déclencheur de webhook.

Vue d'ensemble

Applications

API

Auto-hébergement

Contribuer

Créer un Webhook

Gérer les Webhooks

Événements

Format de la charge utile

Validation des Webhooks

En-têtes

Étapes de validation

Exemple (Node.js)

Webhooks vs Workflows

​Créer un Webhook

​Gérer les Webhooks

​Événements

​Format de la charge utile

​Validation des Webhooks

​En-têtes

​Étapes de validation

​Exemple (Node.js)

​Webhooks vs Workflows

Créer un Webhook

Gérer les Webhooks

Événements

Format de la charge utile

Validation des Webhooks

En-têtes

Étapes de validation

Exemple (Node.js)

Webhooks vs Workflows