Les webhooks envoient des données à vos systèmes en temps réel lorsque des événements se produisent dans Twenty — aucune interrogation n’est nécessaire. Utilisez-les pour maintenir les systèmes externes synchronisés, déclencher des automatisations ou envoyer des alertes.
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 |
{
"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 |
|---|
événement | Ce qui s’est passé (par exemple, person.created) |
données | L’enregistrement complet qui a été créé/mis à jour/supprimé |
horodatage | 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 isValid = expectedSignature === req.headers["x-twenty-webhook-signature"];
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 |
