This repository contains a Python Flask application (app.py) designed to receive and handle Twitter webhook events, including the initial CRC (Challenge-Response Check) validation.

• Handles Twitter's CRC GET requests for webhook URL validation.
• Receives and logs incoming POST requests containing webhook event data.
• Can be run with Flask's built-in development server or a WSGI server like Waitress.

• Python 3.x
• pip (Python package installer)
• A Twitter Developer App with a Consumer Secret.

1. Clone the repository (if you haven't already):

   git clone <your-repository-url>
   cd <your-repository-directory>

2. Set the TWITTER_CONSUMER_SECRET environment variable: This is crucial for the CRC validation.

   export TWITTER_CONSUMER_SECRET="your_twitter_app_consumer_secret"

   Replace "your_twitter_app_consumer_secret" with your actual secret. You might want to add this to your shell's configuration file (e.g., .bashrc, .zshrc) for persistence.

3. Install dependencies: Navigate to the directory containing requirements.txt and run:

   pip install -r requirements.txt

The application can be run in two modes:

• Development Mode (using Flask's built-in server): This mode is useful for local development and debugging.

  python app.py --debug

  The application will typically run on http://127.0.0.1:5000/.

• Production Mode (using Waitress WSGI server): Waitress is a production-quality WSGI server.

  python app.py

  By default, this will run the application on http://0.0.0.0:8080/, making it accessible from other devices on your network.

  When the application starts, you will see output similar to this:

  --- Starting Webhook App ---
  Using TWITTER_CONSUMER_SECRET from environment variable.
  Running with Waitress WSGI server on 0.0.0.0:8080
  

  Or, for debug mode:

  --- Starting Webhook App ---
  Using TWITTER_CONSUMER_SECRET from environment variable.
  Running in DEBUG mode (Flask development server)
   * Serving Flask app 'app'
   * Debug mode: on
  WARNING: This is a development server. Do not use it in a production deployment.
  Use a production WSGI server instead.
   * Running on http://127.0.0.1:5000
  Press CTRL+C to quit
   * Restarting with stat
  --- Starting Webhook App ---
  Using TWITTER_CONSUMER_SECRET from environment variable.
  Running in DEBUG mode (Flask development server)
   * Debugger is active!
   * Debugger PIN: ...
  

This is the primary endpoint for Twitter webhooks.

• GET /webhooks/twitter:

  • Purpose: Used by Twitter for the CRC (Challenge-Response Check) when you register or update a webhook URL.
  • Request: Twitter sends a GET request with a crc_token query parameter.

    GET /webhooks/twitter?crc_token=ABC123XYZ
    

  • Response: The application generates an HMAC-SHA256 hash of the crc_token using your TWITTER_CONSUMER_SECRET and returns it in a JSON response.

    {
      "response_token": "sha256=actual_base64_encoded_hash_here"
    }

  • Logging: The application will print information about the received GET request and the crc_token.

• POST /webhooks/twitter:

  • Purpose: Used by Twitter to send actual webhook event data (e.g., new tweets, mentions, direct messages, etc., depending on your subscription).
  • Request: Twitter sends a POST request with a JSON body containing the event payload.
  • Response: The application logs the received JSON data (if present) and returns an empty 200 OK response to acknowledge receipt.
  • Logging:
    • If JSON data is received:

      --- Received Webhook Event ---
      {
        "event_type": "...",
        ...
      }
      -----------------------------
      

    • If the POST request has a non-JSON or empty body:

      --- Received POST request with non-JSON or empty body ---
      Body: <actual body content if any>
      --------------------------------------------------------
      

1. Start app.py (e.g., python app.py). Make sure it's accessible from the internet (e.g., using a tool like ngrok if running locally).
2. When you provide your webhook URL (e.g., https://your-public-url.com/webhooks/twitter) to Twitter (either via API or the developer portal), Twitter will send a GET request to this URL with a crc_token.
3. app.py will handle this GET request, perform the CRC validation, and respond correctly.
4. If the CRC is successful, Twitter will register your webhook.
5. Subsequently, Twitter will send POST requests with event data to this same URL. app.py will log these events.