Introduction

​

API Webhook v2

​

Panoramica

La Webhooks API v2 consente agli sviluppatori di ricevere notifiche di eventi in tempo reale dagli account X tramite messaggi JSON basati su webhook. Queste API permettono di registrare e gestire i webhook, sviluppare applicazioni consumer per elaborare gli eventi e garantire comunicazioni sicure tramite verifiche challenge‑response (CRC) e intestazioni di firma.

​

Riepilogo delle funzionalità

Piano	Prezzo	Numero di webhook
Self-Serve Pro	5.000 $/mese	1
Enterprise	Contatta il team vendite	5+

​

Prodotti che supportano i webhook

Questi sono i prodotti che attualmente supportano la ricezione di eventi tramite webhook:

• Account Activity API (AAA)
• Filtered Stream

​

Gestione dei webhook

L’Account Activity API fornisce messaggi JSON basati su webhook ogni volta che si verificano eventi associati ad account X sottoscritti al tuo servizio. X recapita tali attività al webhook che hai registrato. Nei passaggi seguenti imparerai a gestire i webhook e gli utenti sottoscritti.

Imparerai a registrare, visualizzare e rimuovere sia i webhook sia gli utenti sottoscritti. Useremo semplici comandi cURL per inviare richieste ai vari endpoint dell’API. cURL è uno strumento da riga di comando per inviare o recuperare dati utilizzando la sintassi degli URL.

Ci sono diversi aspetti da considerare prima di poter iniziare a ricevere eventi webhook nella tua applicazione consumer di eventi. Come descritto di seguito, dovrai creare una X App, ottenere l’accesso all’Account Activity API e sviluppare una web app che consumi eventi webhook. 

​

1. Sviluppa una Webhook Consumer App

Per registrare un nuovo webhook associato alla tua X App, dovrai sviluppare, distribuire e ospitare un’app web che riceva gli eventi webhook di X e risponda alle nostre richieste di sicurezza.

Prima di iniziare, ti consigliamo di dare un’occhiata alle nostre sample apps!

• Crea un’app web con un URL HTTPS pubblicamente accessibile che fungerà da endpoint del webhook per ricevere gli eventi.
  • Il path della URI è totalmente a tua discrezione. Questo esempio è valido: https://mydomain.com/service/listen
  • Se stai gestendo webhooks da varie fonti, uno schema comune è: https://mydomain.com/webhook/twitter
  • Nota che l’URL specificato non può includere una porta (https://mydomain.com:5000/NoWorkie).
• Un primo passo è scrivere codice che riceva una richiesta GET di X Challenge Response Check (CRC) e risponda con un JSON correttamente formattato.
• Registra l’URL del tuo webhook. Invierai una richiesta POST all’endpoint /2/webhooks con l’URL nel body JSON. Quando effettui questa richiesta, X invierà una richiesta CRC alla tua app web.
• Quando un webhook viene registrato correttamente, la risposta includerà un webhook id. Questo webhook id sarà necessario in seguito quando effettuerai richieste ai prodotti che supportano i webhook.
• X invierà richieste POST contenenti eventi all’URL che hai registrato. Questi eventi saranno codificati in JSON. Vedi qui esempi di payload JSON del webhook.

​

Facoltativo: utilizzare xurl per i test

A fini di test, lo strumento xurl ora supporta webhook temporanei! Installa la versione più recente del progetto xurl da GitHub, configura l’autorizzazione, quindi esegui:

xurl webhook start

Questo genererà un URL webhook pubblico temporaneo, gestirà automaticamente tutti i controlli CRC e registrerà gli eventi di sottoscrizione in arrivo. È un ottimo modo per verificare la configurazione prima del deployment. Output di esempio:

Avvio del server webhook con ngrok...
Inserisci il tuo authtoken ngrok (lascia vuoto per utilizzare la variabile d'ambiente NGROK_AUTHTOKEN):

Tentativo di utilizzo della variabile d'ambiente NGROK_AUTHTOKEN per l'autenticazione ngrok.
Configurazione di ngrok per l'inoltro alla porta locale: 8080
Tunnel ngrok stabilito!
  URL di inoltro: https://<your-ngrok-subdomain>.ngrok-free.app -> localhost:8080

Utilizza questo URL per la registrazione del webhook delle X API: https://<your-ngrok-subdomain>.ngrok-free.app/webhook

Avvio del server HTTP locale per gestire le richieste dal tunnel ngrok (inoltrate da https://<your-ngrok-subdomain>.ngrok-free.app)...

Note importanti

• Durante la registrazione dell’URL del webhook, la tua web app deve utilizzare il consumer secret della tua App per la cifratura del controllo CRC.

• Tutti i Messaggi Diretti in arrivo saranno recapitati tramite webhook. Anche tutti i Messaggi Diretti inviati tramite POST /2/dm_conversations/with/:participant_id/messages saranno recapitati tramite webhook. In questo modo la tua web app può rilevare i Messaggi Diretti inviati tramite un client diverso.

• Se hai più di una web app che condivide lo stesso URL del webhook e lo stesso utente associato a ciascuna app, lo stesso evento verrà inviato al tuo webhook più volte (una per ogni web app).

• In alcuni casi, il tuo webhook può ricevere eventi duplicati. La tua app webhook dovrebbe gestire questa eventualità ed effettuare la deduplicazione in base all’id evento.

• Vedi il codice di esempio:

  • Account Activity API Setup, una web app Node che mostra gli eventi del webhook utilizzando il tier Enterprise dell’Account Activity API.

​

2. Protezione dei webhook

Le API basate su webhook di X offrono due metodi per verificare la sicurezza del tuo server webhook:

1. I controlli challenge-response consentono a X di confermare l’effettiva titolarità della web app che riceve gli eventi webhook.
2. L’intestazione di firma in ogni richiesta POST ti consente di verificare che X sia l’origine dei webhook in arrivo.

Consulta la sezione Controllo CRC per i requisiti di implementazione.

​

3. The Webhooks API

I webhook sono gestiti tramite la Webhook Management API. Tutti gli endpoint richiedono l’autenticazione OAuth2 App only con Bearer Token.

​

Aggiungere un webhook

POST /2/webhooks

Descrizione:

Crea una configurazione di webhook. L’URL di callback https pubblicamente accessibile deve essere incluso nel corpo JSON.
Iniziamo registrando un nuovo URL di webhook per il contesto applicativo indicato.

Autenticazione:

OAuth2 App only Bearer Token

• Bearer token <BEARER_TOKEN> ad es. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Parametri (corpo JSON):

{
    "url": "<il tuo URL di callback https accessibile pubblicamente>"
}

• URL <URL> p.es. https://yourdomain.com/webhooks/twitter/

Richiesta: Copia il seguente comando cURL nel terminale dopo aver apportato le seguenti modifiche:

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

Risposte:

Esito positivo (200 OK)

Una risposta positiva indica che il webhook è stato creato e che il controllo CRC iniziale è stato superato.

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

Errore (400 Bad Request)

Le risposte con errore restituiscono un oggetto di errore standard.

{
    "errors": [
      {
        "message": "<Motivo>: <Dettagli>"
      }
    ],
    "title": "Richiesta non valida",
    "detail": "Uno o più parametri della richiesta non sono validi.",
    "type": "https://api.twitter.com/2/problems/invalid-request"
}

Cause comuni di errore includono:

Motivo	Descrizione
CrcValidationFailed	L’URL di callback non ha risposto correttamente al controllo CRC (ad esempio, timeout, risposta errata).
UrlValidationFailed	L’URL di callback fornito non soddisfa i requisiti (ad esempio, non è https, formato non valido).
DuplicateUrlFailed	Per l’URL di callback fornito risulta già registrato un webhook dalla tua applicazione.
WebhookLimitExceeded	La tua applicazione ha raggiunto il numero massimo di configurazioni di webhook consentite.

​

Visualizzare un webhook

GET /2/webhooks

Descrizione: Recupera tutte le configurazioni di webhook associate alla tua applicazione (account sviluppatore).

Autenticazione:

OAuth2 App only Bearer Token

• Bearer token <BEARER_TOKEN> ad es. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

• URL <URL> ad es. https://yourdomain.com/webhooks/twitter/

Richiesta: Esegui il seguente comando per recuperare tutti gli URL dei webhook registrati e i relativi statuses per l’app indicata.

Copia la seguente richiesta cURL nel tuo terminale dopo aver apportato le seguenti modifiche:

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

Operazione riuscita (200 OK)

Restituisce un elenco di configurazioni webhook. L’elenco è vuoto se non è stato configurato alcun webhook.

Esempio (con un webhook configurato):

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

Esempio (nessun webhook configurato):

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

​

Rimozione di un webhook

DELETE /2/webhooks/:webhook_id

Descrizione: Elimina una configurazione di webhook utilizzando il relativo webhook_id specifico. L’ID può essere ottenuto dalla risposta di creazione POST /2/webhooks o dalla risposta di elenco GET /2/webhooks.

Autenticazione:

OAuth2 App only Bearer Token

• Bearer Token <BEARER_TOKEN> ad es. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Parametri del percorso:

Parametro	Descrizione
webhook_id	L’id del webhook da eliminare.

Richiesta: Esegui il seguente comando per rimuovere il webhook dalla configurazione dell’App indicata.

Copia la seguente richiesta cURL nella riga di comando dopo aver apportato le modifiche indicate:

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

  **Risposte:**

Successo (200 OK)

Restituisce una risposta JSON con lo stato “deleted” impostato su true se l’eliminazione è avvenuta correttamente.

Esempio (con eliminazione riuscita del webhook):

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

Errore (400 Bad Request)

Motivo	Descrizione
WebhookIdInvalid	Il webhook_id fornito non è stato trovato o non è associato alla tua App.

​

Convalidare e riattivare il webhook

PUT /2/webhooks/:webhook_id

Descrizione: Avvia il controllo di risposta alla sfida (CRC) per l’URL del webhook indicato. Se il controllo ha esito positivo, restituisce 200 e riattiva il webhook impostandone lo stato su valid.

Autenticazione:

OAuth2 App Only Bearer Token

• Bearer token <BEARER_TOKEN> es. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Parametri di percorso:

Parametro	Descrizione
webhook_id	L’id del webhook da convalidare.

Richiesta: Esegui il seguente comando per convalidare il webhook utilizzando la configurazione dell’applicazione fornita.

Copia la seguente richiesta cURL nel tuo terminale dopo aver apportato le modifiche indicate di seguito:

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

  **Risposte:**

Successo (200 OK)

Una risposta 200 OK indica che la richiesta di controllo CRC è stata avviata. Non garantisce che il controllo CRC sia stato superato. Il campo valid nella risposta riflette lo stato dopo il tentativo di verifica. Se il controllo CRC ha esito positivo, lo stato del webhook verrà aggiornato a valido. È possibile verificare lo stato corrente utilizzando GET /2/webhooks.

{
  "data": {
    "valid": true // Indica lo stato dopo il completamento del tentativo di verifica CRC
  }
}

Errore (400 Bad Request)

Motivo	Descrizione
WebhookIdInvalid	Il webhook_id fornito non è stato trovato oppure non è associato alla tua App.
CrcValidationFailed	L’URL di callback non ha risposto correttamente alla richiesta di verifica CRC.

​

4. Il controllo CRC

Il Challenge Response Check (CRC) è il meccanismo con cui X verifica che la callback URL fornita sia valida e sotto il tuo controllo.

Quando viene attivato il CRC:

• Durante la registrazione iniziale del webhook (POST /2/webhooks)
• Ogni ora da parte di X per la verifica
• Manualmente tramite PUT /2/webhooks/:id

Esempio:

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

Esempio di body della risposta JSON:

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

Come costruire la risposta:

• Usa crc_token come messaggio
• Usa il consumer secret dell’App come chiave
• Crea un hash HMAC SHA-256
• Codifica il risultato in Base64

​

App di esempio

• Simple webhook server
  • Un singolo script Python che mostra come rispondere al controllo CRC e accettare eventi POST.
• Account Activity API sample dashboard
  • Un’app web scritta con bun.sh che consente di gestire webhook, sottoscrizioni e ricevere eventi in tempo reale direttamente nell’App.