Receive Shopify webhooks on Flask API

In this tutorial, we will configure a Flask API to receive webhooks using Webhook Relay. This allows you to receive webhooks even when your Flask application is running locally or behind a firewall.

Prerequisites

• A Webhook Relay account (sign up here)
• Python 3.8+ installed
• Webhook Relay CLI installed (installation guide)

Step 1: Install Flask with uv

First, let's set up a new Python project and install Flask using uv, a fast Python package installer:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a new project directory
mkdir flask-webhook-server
cd flask-webhook-server

# Create a virtual environment and install Flask
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install flask

Step 2: Create the Flask Application

Create a file named app.py with the following content:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.get_json()
    headers = dict(request.headers)
    
    print("=" * 50)
    print("Received webhook!")
    print(f"Headers: {headers}")
    print(f"Payload: {data}")
    print("=" * 50)
    
    return jsonify({"status": "received", "message": "Webhook processed successfully"}), 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=4444, debug=True)

This simple Flask application:

• Listens on port 4444
• Accepts POST requests at /webhook
• Logs the headers and payload to the console
• Returns a success response

Step 3: Start the Flask Server

Run your Flask application:

python app.py

You should see output indicating the server is running:

 * Running on http://0.0.0.0:4444

Step 4: Set up Webhook Relay Forwarding

In a new terminal window, authenticate with Webhook Relay and start forwarding webhooks:

# Login to Webhook Relay (get your token from https://my.webhookrelay.com/tokens)
relay login -k your-token-key -s your-token-secret

# Start forwarding webhooks to your Flask server
relay forward -b shopify-webhooks http://localhost:4444/webhook

You'll see output like:

Forwarding:
https://xxx.hooks.webhookrelay.com -> http://localhost:4444/webhook
Starting webhook relay agent...

Copy the public URL (e.g., https://xxx.hooks.webhookrelay.com) - this is where webhooks will be sent.

Step 5: Test with a Sample Webhook

Now let's send a test webhook to your Flask server using curl:

curl -X POST https://xxx.hooks.webhookrelay.com \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Topic: orders/create" \
  -d '{
    "id": 12345,
    "order_number": "1001",
    "email": "[email protected]",
    "total_price": "99.99",
    "currency": "USD",
    "line_items": [
      {
        "title": "Sample Product",
        "quantity": 2,
        "price": "49.99"
      }
    ]
  }'

Or use the Webhook Relay UI to send a test webhook:

In your Flask server terminal, you should see the webhook logged:

==================================================
Received webhook!
Headers: {'Host': 'localhost:4444', 'Content-Type': 'application/json', 'X-Shopify-Topic': 'orders/create', ...}
Payload: {'id': 12345, 'order_number': '1001', 'email': '[email protected]', ...}
==================================================

Next Steps

Now that your Flask server is receiving webhooks, you can:

• Process webhook data (save to database, trigger actions, etc.)
• Verify webhook signatures for security
• Handle different webhook types based on headers
• Deploy your Flask app and update the forwarding URL

For production deployments, consider using a process manager like gunicorn and running the Webhook Relay agent as a system service. Check out our installation guide with Docker or Kubernetes for more details.