# Twenty CRM — API & Webhooks

> Résumé de la doc officielle Twenty pour l'intégration avec le Lead Pipeline.
> Sources : [APIs](https://docs.twenty.com/developers/extend/capabilities/apis) | [Webhooks](https://docs.twenty.com/developers/extend/capabilities/webhooks)

---

## 1. APIs

Twenty expose deux types d'API, chacun disponible en **REST** et **GraphQL** :

### Core API — Données (records)

- **REST** : `{BASE_URL}/rest/{object}`
- **GraphQL** : `{BASE_URL}/graphql/`
- CRUD sur People, Companies, Opportunities, Notes, etc.
- Les objets custom ont les mêmes endpoints que les objets natifs

### Metadata API — Modèle de données

- **REST** : `{BASE_URL}/rest/metadata/`
- **GraphQL** : `{BASE_URL}/metadata/`
- Créer/modifier/supprimer des objets et champs
- Configurer les relations entre objets

### Endpoints

| Environnement | Base URL |
|---|---|
| Cloud | `https://api.twenty.com/` |
| Self-hosted | `https://{votre-domaine}/` |
| Local | `http://localhost:3000/` |

### Authentification

Chaque requête nécessite un **API key** dans le header :

```
Authorization: Bearer YOUR_API_KEY
```

**Créer une clé :**
1. Settings → APIs & Webhooks
2. \+ Create key → Nom + date d'expiration → Save
3. **Copier immédiatement** (affichée une seule fois)

On peut assigner un **rôle** à une clé API (Settings → Roles → Assignment → API Keys) pour limiter les permissions.

### Batch Operations

| Limite | Valeur |
|---|---|
| Requêtes | **100 appels / minute** |
| Batch size | **60 records / appel** |

- REST et GraphQL supportent le batch (create, update, delete)
- **GraphQL uniquement** : batch upsert (create or update en un appel)
- Utiliser les noms pluriels en GraphQL (`CreateCompanies` au lieu de `CreateCompany`)

### API Playground

Disponible dans l'UI : Settings → APIs & Webhooks → REST API ou GraphQL API.
Documentation interactive générée selon le modèle de données du workspace.

---

## 2. Webhooks

Notifications en temps réel quand un événement se produit dans Twenty (pas de polling).

### Créer un Webhook

1. Settings → APIs & Webhooks → Webhooks
2. \+ Create webhook
3. Entrer l'URL (doit être accessible publiquement)
4. Save → actif immédiatement

### Événements supportés

| Événement | Exemples |
|---|---|
| Record Created | `person.created`, `company.created`, `note.created` |
| Record Updated | `person.updated`, `company.updated`, `opportunity.updated` |
| Record Deleted | `person.deleted`, `company.deleted` |

> Pas de filtrage par type d'événement pour le moment — tous les events sont envoyés à l'URL.

### Format du payload

```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` | Type d'événement (`person.created`, etc.) |
| `data` | Le record complet (créé/modifié/supprimé) |
| `timestamp` | Date de l'événement (UTC) |

Répondre avec un **status HTTP 2xx** pour confirmer la réception.

### Validation des signatures

Twenty signe chaque requête webhook avec HMAC SHA256.

**Headers :**

| Header | Description |
|---|---|
| `X-Twenty-Webhook-Signature` | Signature HMAC SHA256 |
| `X-Twenty-Webhook-Timestamp` | Timestamp de la requête |

**Étapes de validation :**

1. Récupérer le timestamp depuis `X-Twenty-Webhook-Timestamp`
2. Construire la chaîne : `{timestamp}:{JSON payload}`
3. Calculer le HMAC SHA256 avec le secret du webhook
4. Comparer avec `X-Twenty-Webhook-Signature`

**Exemple Python :**

```python
import hashlib
import hmac

timestamp = request.headers["X-Twenty-Webhook-Timestamp"]
payload = request.body.decode()
secret = "your-webhook-secret"

string_to_sign = f"{timestamp}:{payload}"
expected = hmac.new(secret.encode(), string_to_sign.encode(), hashlib.sha256).hexdigest()

is_valid = hmac.compare_digest(expected, request.headers["X-Twenty-Webhook-Signature"])
```

### Webhooks vs Workflows

| Méthode | Direction | Cas d'usage |
|---|---|---|
| **Webhooks** | OUT | Notifier des systèmes externes de tout changement |
| **Workflow + HTTP Request** | OUT | Envoyer des données avec logique custom (filtres, transformations) |
| **Workflow Webhook Trigger** | IN | Recevoir des données dans Twenty depuis l'extérieur |

---

## 3. Usage pour le Lead Pipeline

### Sync Pipeline → Twenty (REST API)

```bash
# Créer un lead (person)
POST http://localhost:3000/rest/people
Authorization: Bearer {API_KEY}
Content-Type: application/json

{
  "firstName": "Jean",
  "lastName": "Dupont",
  "email": "jean@example.com",
  "company": "Magiline"
}
```

### Webhook Twenty → Pipeline (notifications)

Configurer un webhook vers le pipeline pour réagir aux changements de statut dans Twenty (ex: lead marqué "Contacted" → déclencher une action).