Introduction

​

Webhooks-API v2

​

Übersicht

Die Webhooks-API v2 ermöglicht Entwicklern, Echtzeitereignis-Benachrichtigungen von X Accounts über webhookbasierte JSON-Nachrichten zu empfangen. Diese APIs erlauben es, Webhooks zu registrieren und zu verwalten, Consumer-Anwendungen zur Ereignisverarbeitung zu entwickeln und die sichere Kommunikation durch Challenge-Response-Prüfungen (CRC) sowie Signatur-Header sicherzustellen.

​

Funktionsübersicht

Tarif	Preis	Anzahl der Webhooks
Self-Serve Pro	5.000 $/Monat	1
Enterprise	Vertrieb kontaktieren	5+

​

Produkte mit Webhook-Unterstützung

Diese Produkte unterstützen derzeit die Zustellung von Ereignissen per Webhook:

• Account Activity API (AAA)
• Filtered Stream

​

Webhooks verwalten

Die Account Activity API stellt webhook-basierte JSON-Nachrichten bereit, sobald Ereignisse für X Accounts auftreten, die Ihren Dienst abonniert haben. X übermittelt diese Aktivitäten an Ihren registrierten Webhook. In den folgenden Schritten erfahren Sie, wie Sie Webhooks und abonnierte Nutzer verwalten.

Sie lernen, wie Sie sowohl Webhooks als auch abonnierte Nutzer registrieren, anzeigen und entfernen. Wir verwenden einfache cURL-Befehle, um Anfragen an die verschiedenen API-endpoints zu senden. cURL ist ein Kommandozeilenwerkzeug zum Senden oder Abrufen von Anfragen unter Verwendung der URL-Syntax.

Bevor Ihre Event-Consumer-Anwendung Webhook-Ereignisse empfangen kann, sind einige Details zu beachten. Wie unten beschrieben, müssen Sie eine X App erstellen, Zugriff auf die Account Activity API erhalten und eine Web-App entwickeln, die Webhook-Ereignisse verarbeitet. 

​

1. Entwickeln Sie eine Webhook-Consumer-App

Um einen neuen Webhook zu registrieren, der Ihrer X App zugeordnet ist, müssen Sie eine Web-App entwickeln, bereitstellen und hosten, die X‑Webhook-Ereignisse empfängt und auf unsere Sicherheitsanforderungen reagiert.

Bevor Sie beginnen, empfehlen wir, unsere Beispiel-Apps anzusehen!

• Erstellen Sie eine Web-App mit einer öffentlich erreichbaren HTTPS-URL, die als Webhook-endpoint zum Empfangen von Ereignissen dient.
  • Der URI‑Pfad ist vollständig Ihnen überlassen. Dieses Beispiel wäre gültig: https://mydomain.com/service/listen
  • Wenn Sie Webhooks aus verschiedenen Quellen empfangen, ist ein gängiges Muster: https://mydomain.com/webhook/twitter
  • Beachten Sie, dass die angegebene URL keine Portangabe enthalten darf (https://mydomain.com:5000/NoWorkie).
• Ein erster Schritt ist das Schreiben von Code, der eine X Challenge Response Check (CRC)‑GET-Anfrage empfängt und mit einer korrekt formatierten JSON-Antwort reagiert.
• Registrieren Sie Ihre Webhook-URL. Sie senden eine POST-Anfrage an ein /2/webhooks endpoint mit der URL im JSON-Body. Wenn Sie diese Anfrage senden, wird X eine CRC-Anfrage an Ihre Web-App senden.
• Wenn ein Webhook erfolgreich registriert wurde, enthält die Antwort eine Webhook-id. Diese Webhook-id wird später benötigt, wenn Sie Anfragen an Produkte stellen, die Webhooks unterstützen.
• X sendet POST-Anfragen mit Ereignissen an die von Ihnen registrierte URL. Diese Ereignisse werden in JSON codiert. Siehe hier für Beispiel-JSON-Payloads von Webhooks.

​

Optional: Verwenden Sie xurl für Tests

Zu Testzwecken unterstützt das Tool xurl jetzt temporäre Webhooks! Installieren Sie die neueste Version des xurl-Projekts von GitHub, konfigurieren Sie Ihre Autorisierung und führen Sie dann Folgendes aus:

xurl webhook start

Dies erzeugt eine temporäre öffentliche Webhook-URL, führt automatisch alle CRC-Prüfungen aus und protokolliert eingehende Abo‑Ereignisse. Das ist eine hervorragende Methode, um Ihre Einrichtung vor der Bereitstellung zu verifizieren. Beispielausgabe:

Webhook-Server mit ngrok wird gestartet...
Geben Sie Ihr ngrok-Authtoken ein (leer lassen, um die Umgebungsvariable NGROK_AUTHTOKEN zu verwenden):

Versuche, die Umgebungsvariable NGROK_AUTHTOKEN für die ngrok-Authentifizierung zu verwenden.
Konfiguriere ngrok für die Weiterleitung an lokalen Port: 8080
Ngrok-Tunnel eingerichtet!
  Weiterleitungs-URL: https://<your-ngrok-subdomain>.ngrok-free.app -> localhost:8080

Verwenden Sie diese URL für Ihre X API-Webhook-Registrierung: https://<your-ngrok-subdomain>.ngrok-free.app/webhook

Lokaler HTTP-Server wird gestartet, um Anfragen vom ngrok-Tunnel zu bearbeiten (weitergeleitet von https://<your-ngrok-subdomain>.ngrok-free.app)...

Wichtige Hinweise

• Beim Registrieren Ihrer Webhook-URL muss Ihre Web-App das Consumer-Secret Ihrer App für die Verschlüsselung der CRC-Prüfung verwenden.

• Alle eingehenden Direct Messages werden über Webhooks zugestellt. Alle Direct Messages, die über POST /2/dm_conversations/with/:participant_id/messages gesendet werden, werden ebenfalls über Webhooks zugestellt. So kann Ihre Web-App auch von Direct Messages Kenntnis erhalten, die über einen anderen Client gesendet wurden.

• Wenn mehrere Web-Apps dieselbe Webhook-URL verwenden und derselbe Benutzer jeweils jeder App zugeordnet ist, wird dasselbe Ereignis mehrfach an Ihren Webhook gesendet (einmal pro Web-App).

• In einigen Fällen kann Ihr Webhook doppelte Ereignisse erhalten. Ihre Webhook-App sollte damit umgehen können und anhand der Ereignis-id deduplizieren.

• Beispielcode:

  • Account Activity API Setup, eine Node-Web-App, die Webhook-Ereignisse unter Verwendung der Enterprise-Tier der Account Activity API anzeigt.

​

2. Absicherung von Webhooks

Die webhookbasierten APIs von X bieten zwei Methoden, um die Sicherheit Ihres Webhook-Servers zu gewährleisten:

1. Die Challenge-Response-Prüfungen ermöglichen X, die Eigentümerschaft der Web-App zu verifizieren, die Webhook-Ereignisse empfängt.
2. Der Signatur-Header in jeder POST-Anfrage ermöglicht es Ihnen, zu bestätigen, dass X die Quelle der eingehenden Webhooks ist.

Siehe den Abschnitt zur CRC-Prüfung für Implementierungsanforderungen.

​

3. Die Webhooks-API

Webhooks werden über die Webhook-Management-API verwaltet. Alle endpoints erfordern die Authentifizierung mit einem OAuth2 App only Bearer Token.

​

Hinzufügen eines Webhooks

POST /2/webhooks

Beschreibung:

Erstellen Sie eine Webhook-Konfiguration. Ihre öffentlich zugängliche https-Callback-URL muss im JSON-Body übergeben werden.
Beginnen wir mit der Registrierung einer neuen Webhook-URL für den entsprechenden Anwendungskontext.

Authentifizierung:

OAuth2 App only Bearer Token

• Bearer Token <BEARER_TOKEN> z. B. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Parameter (JSON-Body):

{
    "url": "<Ihre öffentlich zugängliche HTTPS-Callback-URL>"
}

• URL <URL> z. B. https://yourdomain.com/webhooks/twitter/

Anforderung: Kopieren Sie die folgende cURL-Anfrage in Ihre Befehlszeile, nachdem Sie die folgenden Anpassungen vorgenommen haben:

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

Antworten:

Erfolg (200 OK)

Eine erfolgreiche Antwort zeigt an, dass der Webhook erstellt wurde und die initiale CRC-Prüfung bestanden wurde.

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

Fehler (400 Bad Request)

Fehler geben ein Standard-Fehlerobjekt zurück.

{
    "errors": [
      {
        "message": "<Grund>: <Details>"
      }
    ],
    "title": "Ungültige Anfrage",
    "detail": "Ein oder mehrere Parameter Ihrer Anfrage sind ungültig.",
    "type": "https://api.twitter.com/2/problems/invalid-request"
}

Häufige Gründe für Fehler sind:

Grund	Beschreibung
CrcValidationFailed	Die Callback-URL hat nicht korrekt auf die CRC-Prüfung geantwortet (z. B. Zeitüberschreitung, falsche Antwort).
UrlValidationFailed	Die angegebene Callback-URL erfüllt die Anforderungen nicht (z. B. nicht https, ungültiges Format).
DuplicateUrlFailed	Für die angegebene Callback-URL ist durch Ihre Anwendung bereits ein Webhook registriert.
WebhookLimitExceeded	Ihre Anwendung hat die maximale Anzahl zulässiger Webhook-Konfigurationen erreicht.

​

Anzeigen eines Webhooks

GET /2/webhooks

Beschreibung: Rufen Sie alle Webhook-Konfigurationen ab, die mit Ihrer App (Developer-Konto) verknüpft sind.

Authentifizierung:

OAuth2 App only Bearer Token

• Bearer Token <BEARER_TOKEN> z. B. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

• URL <URL> z. B. https://yourdomain.com/webhooks/twitter/

Anfrage: Führen Sie den folgenden Befehl aus, um alle registrierten Webhook-URLs und deren Status für die angegebene App abzurufen.

Kopieren Sie die folgende cURL-Anfrage in Ihre Kommandozeile und nehmen Sie zuvor die folgenden Anpassungen vor:

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

Erfolg (200 OK)

Gibt eine Liste der Webhook-Konfigurationen zurück. Die Liste ist leer, wenn keine Webhooks konfiguriert sind.

Beispiel (mit einem konfigurierten Webhook):

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

Beispiel (ohne konfigurierte Webhooks):

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

​

Entfernen eines Webhooks

DELETE /2/webhooks/:webhook_id

Beschreibung: Löschen Sie eine Webhook-Konfiguration mithilfe der spezifischen webhook_id. Die ID kann aus der Erstellungsmeldung von POST /2/webhooks oder der Listing-Antwort von GET /2/webhooks entnommen werden.

Authentifizierung:

OAuth2 App only Bearer Token

• Bearer Token <BEARER_TOKEN> z. B. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Pfadparameter:

Parameter	Beschreibung
webhook_id	Die ID des zu löschenden Webhooks.

Anfrage: Führen Sie den folgenden Befehl aus, um den Webhook aus der Konfiguration der angegebenen App zu entfernen.

Kopieren Sie die folgende cURL-Anfrage in Ihre Befehlszeile, nachdem Sie die untenstehenden Platzhalter angepasst haben:

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

  **Antworten:**

Erfolg (200 OK)

Gibt eine JSON-Antwort mit dem Status „deleted“ auf true zurück, wenn das Löschen erfolgreich war.

Beispiel (bei erfolgreichem Löschen des Webhooks):

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

Fehler (400 Bad Request)

Grund	Beschreibung
WebhookIdInvalid	Die angegebene webhook_id wurde nicht gefunden oder ist Ihrer App nicht zugeordnet.

​

Webhook validieren und erneut aktivieren

PUT /2/webhooks/:webhook_id

Beschreibung: Führt die Challenge-Response-Prüfung (CRC) für die URL des angegebenen Webhooks aus. Bei erfolgreicher Prüfung wird ein 200-Status zurückgegeben und der Webhook durch Setzen seines Status auf valid erneut aktiviert.

Authentifizierung:

OAuth2 App only Bearer Token

• Bearer Token <BEARER_TOKEN> z. B. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Pfadparameter:

Parameter	Beschreibung
webhook_id	Die id des zu validierenden Webhooks.

Anfrage: Führen Sie den folgenden Befehl aus, um den Webhook anhand der Konfiguration der angegebenen App zu validieren.

Kopieren Sie den folgenden cURL-Befehl in Ihre Befehlszeile, nachdem Sie die entsprechenden Anpassungen vorgenommen haben:

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

  **Antworten:**

Erfolg (200 OK)

Eine 200-OK-Antwort zeigt an, dass die CRC-Prüfanfrage initiiert wurde. Sie garantiert nicht, dass die CRC-Prüfung bestanden wurde. Das Feld valid in der Antwort spiegelt den Status nach dem Prüfversuch wider. Wenn die CRC-Prüfung erfolgreich ist, wird der Status des Webhooks auf „gültig“ aktualisiert. Sie können den aktuellen Status mit GET /2/webhooks überprüfen.

{
  "data": {
    "valid": true // Gibt den Status nach Abschluss der CRC-Prüfung an
  }
}

Fehler (400 Bad Request)

Grund	Beschreibung
WebhookIdInvalid	Die angegebene webhook_id wurde nicht gefunden oder ist Ihrer App nicht zugeordnet.
CrcValidationFailed	Die Callback-URL hat nicht korrekt auf die CRC-Prüfanfrage geantwortet.

​

4. Die CRC-Prüfung

Die Challenge-Response-Prüfung (CRC) ist die Methode, mit der X überprüft, dass die von Ihnen angegebene Callback-URL gültig ist und dass Sie sie kontrollieren.

Wann die CRC ausgelöst wird:

• Bei der erstmaligen Webhook-Registrierung (POST /2/webhooks)
• Stündlich durch X zur Validierung
• Manuell über PUT /2/webhooks/:id

Beispiel:

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

Beispiel-JSON-Antworttext:

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

So erstellen Sie die Antwort:

• Verwenden Sie crc_token als Nachricht
• Verwenden Sie das Consumer Secret der App als Schlüssel
• Erstellen Sie einen HMAC-SHA-256-hash
• Kodieren Sie das Ergebnis in Base64

​

Beispiel-Apps

• Einfacher Webhook-Server
  • Ein einzelnes Python-Skript, das zeigt, wie Sie auf die CRC-Prüfung reagieren und POST-Ereignisse akzeptieren.
• Account Activity API Beispiel-Dashboard
  • Eine mit bun.sh entwickelte Web-App, mit der Sie Webhooks und Abonnements verwalten und Live-Ereignisse direkt in der App empfangen können.