API Webhooks v2

Aperçu

L’API Webhooks v2 permet aux développeurs de recevoir, en temps réel, des notifications d’événements de comptes X via des messages JSON envoyés par webhook. Cette API vous permet d’enregistrer et de gérer des webhooks, de développer des applications consommatrices pour traiter les événements, et de garantir une communication sécurisée grâce aux vérifications de type challenge-réponse (CRC) et aux en-têtes de signature.

Récapitulatif des fonctionnalités

Niveau	Tarification	Nombre de webhooks
Self-Serve Pro	5 000 $/mois	1
Enterprise	Contacter l’équipe commerciale	5+

Produits prenant en charge les webhooks

Voici les produits qui prennent actuellement en charge la diffusion d’événements via webhook :

Gérer les webhooks

L’Account Activity API vous envoie des messages JSON via webhook dès qu’un événement est associé à des comptes X abonnés à votre service. X remet ces activités à votre webhook enregistré. Dans les étapes suivantes, vous apprendrez à gérer les webhooks et les utilisateurs abonnés. Vous verrez comment enregistrer, consulter et supprimer des webhooks ainsi que des utilisateurs abonnés. Nous utiliserons de simples commandes cURL pour effectuer des requêtes vers les différents endpoints de l’API. cURL est un outil en ligne de commande permettant d’envoyer ou de récupérer des requêtes en utilisant la syntaxe d’URL. Plusieurs éléments doivent être pris en compte avant de pouvoir commencer à recevoir des événements de webhook dans votre application consommatrice d’événements. Comme décrit ci-dessous, vous devrez créer une X App, obtenir l’accès à l’Account Activity API et développer une application web qui consomme les événements de webhook.

1. Développer une App consommatrice de webhook

Pour enregistrer un nouveau webhook associé à votre X App, vous devez développer, déployer et héberger une application web qui reçoit les événements de webhook X et répond à nos requêtes de sécurité. Avant de commencer, nous vous recommandons de consulter nos exemples d’applications\ !

Créez une application web avec une URL HTTPS accessible publiquement qui servira d’endpoint de webhook pour recevoir les événements.
- Le chemin de l’URI est entièrement à votre discrétion. L’exemple suivant est valide : https://mydomain.com/service/listen
- Si vous recevez des webhooks provenant de différentes sources, un modèle courant est : https://mydomain.com/webhook/twitter
- Notez que l’URL spécifiée ne peut pas inclure de port (https://mydomain.com:5000/NoWorkie).
Une première étape consiste à écrire du code qui reçoit une requête GET X Challenge Response Check (CRC) et qui répond avec une réponse JSON correctement formatée.
Enregistrez votre URL de webhook. Vous effectuerez une requête POST vers l’endpoint /2/webhooks avec l’URL dans le corps JSON. Lorsque vous enverrez cette requête, X adressera une requête CRC à votre application web.
Lorsqu’un webhook est enregistré avec succès, la réponse inclut un id de webhook. Cet id de webhook sera nécessaire ultérieurement lors de requêtes vers des produits qui prennent en charge les webhooks.
X enverra des requêtes POST contenant des événements à l’URL que vous avez enregistrée. Ces événements seront encodés en JSON. Consultez ici pour des exemples de payloads JSON de webhook.

Facultatif : utiliser xurl pour les tests

À des fins de test, l’outil xurl prend désormais en charge des webhooks temporaires ! Installez la dernière version du projet xurl sur GitHub, configurez votre autorisation, puis exécutez :

xurl webhook start

Cela générera une URL de webhook publique temporaire, gérera automatiquement toutes les vérifications CRC et enregistrera tous les événements d’abonnement entrants. C’est un excellent moyen de valider votre configuration avant le déploiement. Exemple de sortie :

Démarrage du serveur webhook avec ngrok...
Saisissez votre jeton d'authentification ngrok (laissez vide pour utiliser la variable d'environnement NGROK_AUTHTOKEN) :

Tentative d'utilisation de la variable d'environnement NGROK_AUTHTOKEN pour l'authentification ngrok.
Configuration de ngrok pour rediriger vers le port local : 8080
Tunnel ngrok établi !
  URL de redirection : https://<your-ngrok-subdomain>.ngrok-free.app -> localhost:8080

Utilisez cette URL pour l'enregistrement de votre webhook X API : https://<your-ngrok-subdomain>.ngrok-free.app/webhook

Démarrage du serveur HTTP local pour traiter les requêtes du tunnel ngrok (redirigées depuis https://<your-ngrok-subdomain>.ngrok-free.app)...

Notes importantes

Lors de l’enregistrement de votre URL de webhook, votre application web doit utiliser le consumer secret de votre App pour le chiffrement de la vérification CRC.
Tous les Messages privés entrants seront remis via des webhooks. Tous les Messages privés envoyés via POST /2/dm_conversations/with/:participant_id/messages seront également remis via des webhooks. Cela permet à votre application web d’être informée des Messages privés envoyés depuis un autre client.
Si plusieurs applications web partagent la même URL de webhook et mappent le même utilisateur, le même événement sera envoyé à votre webhook plusieurs fois (une fois par application web).
Dans certains cas, votre webhook peut recevoir des événements en double. Votre application de webhook doit le tolérer et effectuer une déduplication par id d’événement.
Voir l’exemple de code :
- Account Activity API Setup, une application web Node qui affiche les événements de webhook en utilisant le niveau Enterprise de l’Account Activity API.

2. Sécurisation des webhooks

Les API basées sur les webhooks de X proposent deux méthodes pour vérifier la sécurité de votre serveur de webhook :

Les vérifications de type défi-réponse permettent à X de confirmer que vous êtes bien propriétaire de l’application web qui reçoit les événements de webhook.
L’en-tête de signature présent dans chaque requête POST vous permet de confirmer que X est bien la source des webhooks entrants.

Voir la section Vérification CRC pour les exigences de mise en œuvre.

3. L’API Webhooks

Les webhooks sont gérés via l’API de gestion des webhooks. Tous les endpoints nécessitent une authentification OAuth 2.0 App only avec un Jeton Bearer.

Ajouter un webhook

POST /2/webhooks Description : Créez une configuration de webhook. Votre URL de callback https publiquement accessible doit être transmise dans le corps JSON.
Commençons par enregistrer une nouvelle URL de webhook pour le contexte d’application donné. Authentification : OAuth2 App only Jeton Bearer

Jeton Bearer <BEARER_TOKEN> p. ex. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Paramètres (corps JSON) :

{
    "url": "<votre URL de callback https accessible publiquement>"
}

URL <URL> par exemple : https://yourdomain.com/webhooks/twitter/

Requête : Copiez la requête cURL suivante dans votre terminal après avoir apporté les modifications suivantes :

  ```
  curl --request POST --url 'https://api.twitter.com/2/webhooks?url=<URL>' --header 'authorization: Bearer <BEARER_TOKEN>'
  --data '{
"url": "https://yourdomain.com/webhooks/twitter"
          }'
  ```

Réponses : Réussite (200 OK) Une réponse réussie indique que le webhook a été créé et que le contrôle CRC initial a réussi.

{
  "data": {
    "id": "<webhook_id>",
    "url": "<your callback url>",
    "valid": true,
    "created_at": "YYYY-mm-DDTHH:MM:ss.000Z"
  }
}

Échec (400 Bad Request) Les échecs renvoient un objet d’erreur standard.

{
    "errors": [
      {
        "message": "<Raison> : <Détails>"
      }
    ],
    "title": "Requête non valide",
    "detail": "Un ou plusieurs paramètres de votre requête sont non valides.",
    "type": "https://api.twitter.com/2/problems/invalid-request"
}

Raisons courantes d’échec :

Motif	Description
`CrcValidationFailed`	L’URL de rappel n’a pas répondu correctement au contrôle CRC (p. ex. : délai dépassé, réponse incorrecte).
`UrlValidationFailed`	L’URL de rappel fournie ne respecte pas les exigences (p. ex. : non `https`, format invalide).
`DuplicateUrlFailed`	Un webhook est déjà enregistré par votre application pour l’URL de rappel fournie.
`WebhookLimitExceeded`	Votre application a atteint le nombre maximal de configurations de webhook autorisées.

Affichage d’un webhook

GET /2/webhooks Description : Récupérer toutes les configurations de webhook associées à votre application (compte développeur). Authentification : OAuth2 App only Jeton Bearer

Jeton Bearer <BEARER_TOKEN> p. ex. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...
URL <URL> p. ex. https://yourdomain.com/webhooks/twitter/

Requête : Exécutez la commande suivante pour récupérer toutes les URL de webhook enregistrées et leur statut pour l’application donnée. Copiez la requête cURL suivante dans votre terminal après avoir apporté les modifications suivantes :

  ```
  curl --request GET --url 'https://api.twitter.com/2/webhooks' --header 'authorization: Bearer <BEARER_TOKEN>'
  ```

Réussite (200 OK) Renvoie la liste des configurations de webhook. La liste est vide si aucun webhook n’est configuré. Exemple (avec un webhook configuré) :

{
  "data": [
    {
      "created_at": "YYYY-mm-DDTHH:MM:ss.000Z",
      "id": "<webhook_id>",
      "url": "<url de callback>",
      "valid": true
    }
  ],
  "meta": {
    "result_count": 1
  }
}

Exemple (aucun webhook configuré) :

{
  "data": [],
  "meta": {
    "result_count": 0
  }
}

Supprimer un webhook

DELETE /2/webhooks/:webhook_id Description : Supprimez une configuration de webhook à l’aide de son webhook_id spécifique. L’ID peut être obtenu dans la réponse de création POST /2/webhooks ou dans la réponse de liste GET /2/webhooks. Authentification : OAuth2 App only Jeton Bearer

Jeton Bearer <BEARER_TOKEN> p. ex. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Paramètres de chemin :

Paramètre	Description
`webhook_id`	L’id du webhook à supprimer.

Requête : Exécutez la commande suivante pour retirer le webhook de la configuration de l’App fournie. Copiez la requête cURL suivante dans votre terminal après avoir apporté les modifications suivantes :

  ```
  curl --request DELETE --url 'https://api.twitter.com/2/webhooks/:WEBHOOK_ID' --header 'authorization: Bearer <BEARER_TOKEN>'
  ```

  **Réponses :**

Réussite (200 OK) Renvoie une réponse JSON avec l’état « deleted » à true si la suppression a réussi. Exemple (avec suppression réussie du webhook) :

{
  "data": {
    "deleted": true
  }
}

Échec (400 Bad Request)

Raison	Description
`WebhookIdInvalid`	Le `webhook_id` fourni est introuvable ou n’est pas associé à votre App.

Valider et réactiver le webhook

PUT /2/webhooks/:webhook_id Description : Déclenche la vérification de la réponse au défi (CRC) pour l’URL du webhook indiqué. Si la vérification réussit, renvoie 200 et réactive le webhook en définissant son statut sur valid. Authentication : OAuth2 App only Jeton Bearer

Jeton Bearer <BEARER_TOKEN> p. ex. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Path Parameters :

Parameter	Description
`webhook_id`	L’id du webhook à valider.

Request : Exécutez la commande suivante pour valider le webhook à partir de la configuration de l’App fournie. Copiez la requête cURL suivante dans votre terminal après avoir apporté les modifications suivantes :

  ```
  curl --request PUT --url 'https://api.twitter.com/2/webhooks/:WEBHOOK_ID' --header 'authorization: Bearer <BEARER_TOKEN>'
  ```

  **Réponses :**

Succès (200 OK) Une réponse 200 OK indique que la requête de vérification CRC a été lancée. Elle ne garantit pas que la vérification CRC a abouti. Le champ valid dans la réponse reflète l’état après la tentative de vérification. Si la vérification CRC réussit, l’état du webhook sera mis à jour sur « valid ». Vous pouvez vérifier l’état actuel avec GET /2/webhooks.

{
  "data": {
    "valid": true // Indique le statut une fois la tentative de vérification CRC terminée
  }
}

Échec (400 Bad Request)

Raison	Description
`WebhookIdInvalid`	Le `webhook_id` fourni est introuvable ou n’est pas associé à votre App.
`CrcValidationFailed`	L’URL de rappel n’a pas répondu correctement à la requête de vérification CRC.

4. La vérification CRC

La vérification par défi-réponse (CRC) est le mécanisme par lequel X s’assure que l’URL de callback que vous avez fournie est valide et que vous en avez le contrôle. Quand la CRC est déclenchée :

Lors de l’enregistrement initial du webhook (POST /2/webhooks)
Chaque heure par X pour validation
Manuellement via PUT /2/webhooks/:id

Exemple :

GET https://your-webhook-url.com/webhook?crc_token=challenge_string

Exemple de corps de réponse JSON :

{
  "response_token": "sha256=<base64_encoded_hmac_hash>"
}

Comment construire la réponse :

Utiliser crc_token comme message
Utiliser le consumer secret de l’App comme clé
Créer un hash HMAC SHA-256
Encoder le résultat en Base64

Exemples d’Apps

Serveur de webhook simple
- Un script Python unique qui montre comment répondre au contrôle CRC et accepter des événements POST.
Tableau de bord d’exemple Account Activity API
- Une application web écrite avec bun.sh qui permet de gérer des webhooks, des abonnements et de recevoir des événements en direct directement dans l’App.

Présentation

Posts

Users

Messages privés

Likes

List

Spaces

Communautés

Notes de la communauté

Tendances

Médias

Utilisation

Connexions de stream

Conformité

Enterprise v2

Streams des likes

GNIP 2.0

Introduction

API Webhooks v2

Aperçu

Récapitulatif des fonctionnalités

Produits prenant en charge les webhooks

Gérer les webhooks

1. Développer une App consommatrice de webhook

Facultatif : utiliser xurl pour les tests

2. Sécurisation des webhooks

3. L’API Webhooks

Ajouter un webhook

Affichage d’un webhook

Supprimer un webhook

Valider et réactiver le webhook

4. La vérification CRC

Exemples d’Apps

Présentation

Posts

Users

Messages privés

Likes

List

Spaces

Communautés

Notes de la communauté

Tendances

Médias

Utilisation

Connexions de stream

Conformité

Enterprise v2

Streams des likes

GNIP 2.0

​API Webhooks v2

​Aperçu

​Récapitulatif des fonctionnalités

​Produits prenant en charge les webhooks

​Gérer les webhooks

​1. Développer une App consommatrice de webhook

​Facultatif : utiliser xurl pour les tests

​2. Sécurisation des webhooks

​3. L’API Webhooks

​Ajouter un webhook

​Affichage d’un webhook

​Supprimer un webhook

​Valider et réactiver le webhook

​4. La vérification CRC

​Exemples d’Apps

API Webhooks v2

Aperçu

Récapitulatif des fonctionnalités

Produits prenant en charge les webhooks

Gérer les webhooks

1. Développer une App consommatrice de webhook

Facultatif : utiliser xurl pour les tests

2. Sécurisation des webhooks

3. L’API Webhooks

Ajouter un webhook

Affichage d’un webhook

Supprimer un webhook

Valider et réactiver le webhook

4. La vérification CRC

Exemples d’Apps