Learn how to build a secure webhook receiver in Python that listens for external events — from support tickets to GitHub pushes — and automatically triggers LLM pipelines in response. This hands-on lesson covers HMAC signature validation, async processing, and structured AI output, so you can connect any external system to an AI workflow.

Imagine your company's customer support ticketing system receives a new high-priority complaint at 2 AM. Nobody's watching a dashboard. Nobody's running a script. But within seconds, an AI pipeline kicks off automatically — it classifies the complaint, drafts a response, escalates it to the right team, and logs everything. No human triggered it. The external event was the trigger.
That's the power of webhooks combined with LLM pipelines. Instead of your code constantly asking "has anything happened yet?" (a pattern called polling), external systems tell your code the moment something happens — and your code immediately puts an AI to work on it. This pattern is everywhere in production: Stripe fires a webhook when a payment fails, GitHub fires one when code is pushed, Salesforce fires one when a deal closes. If you can catch those events and pipe them into an LLM, you've built something genuinely useful.
By the end of this lesson, you'll have built a working webhook receiver in Python that listens for external events, validates them securely, and triggers an LLM pipeline in response. We'll use a customer support scenario throughout so the examples stay grounded in something real.
What you'll learn:
You should be comfortable writing Python functions and have a basic understanding of HTTP requests (GET vs POST). You don't need prior webhook experience, but you should have your OpenAI API key ready. If you haven't set that up yet, work through Using the OpenAI API with Python first. You'll need Flask installed (pip install flask openai) and a tool like ngrok to expose your local server for testing.
Before writing a single line of code, let's nail down the concept, because webhooks confuse a lot of people who come from a polling mindset.
Polling means your code periodically checks whether something has happened. Think of it like repeatedly refreshing your email inbox every five seconds to see if a new message arrived. It works, but it's wasteful — most of the time you're checking and nothing has changed.
A webhook inverts this relationship. Instead of you asking "anything new?", the external service calls you the moment something happens. It's like setting up an alert so your phone rings the instant a new email arrives, rather than you constantly hitting refresh.
Mechanically, a webhook is just an HTTP POST request that an external service sends to a URL you provide. That URL points to a web server you control — your webhook receiver or webhook endpoint. The POST request contains a JSON payload describing what happened: who triggered it, what changed, relevant data.
Here's the flow:
https://myapp.com/webhooks/support whenever a new ticket is created")Key insight
Step 4 and 5 need to be treated separately. Your webhook receiver must respond with 200 OK immediately — most external services will timeout in 5-30 seconds and retry if they don't get a response. Any heavy LLM processing should happen asynchronously after you've acknowledged receipt.
Flask is a lightweight Python web framework — it lets you define URL routes and the functions that handle requests to those routes. It's the right tool for a simple webhook receiver because it gets out of the way and lets you focus on the logic.
Install the dependencies:
pip install flask openai python-dotenv
Here's a minimal webhook receiver that accepts incoming POST requests:
# webhook_receiver.py
from flask import Flask, request, jsonify
import json
app = Flask(__name__)
@app.route('/webhooks/support', methods=['POST'])
def handle_support_webhook():
# Flask makes the raw request body available via request.data
payload_bytes = request.data
# Parse the JSON body
try:
payload = request.get_json(force=True)
except Exception as e:
return jsonify({"error": "Invalid JSON"}), 400
print(f"Received webhook: {json.dumps(payload, indent=2)}")
# Always return 200 quickly to acknowledge receipt
return jsonify({"status": "received"}), 200
if __name__ == '__main__':
app.run(port=5000, debug=True)
Run this with python webhook_receiver.py, and you'll have a server listening on http://localhost:5000/webhooks/support. You can test it immediately with curl:
curl -X POST http://localhost:5000/webhooks/support \
-H "Content-Type: application/json" \
-d '{"ticket_id": "T-1042", "priority": "high", "subject": "Cannot access my account", "body": "I have been locked out for 3 days. This is urgent.", "customer_email": "alex.torres@example.com"}'
Your terminal running Flask should print the received payload. That's your webhook receiver working.
Tip
To expose your local Flask server to the internet for real webhook testing, run ngrok http 5000 in a separate terminal. ngrok gives you a public URL like https://abc123.ngrok.io that tunnels to your local machine. You'd register https://abc123.ngrok.io/webhooks/support with the external service.
Here's a problem with the receiver you just built: anyone on the internet can POST to that URL. A malicious actor could send you forged payloads that trigger your LLM pipeline with crafted inputs — costing you money, corrupting your data, or worse.
Real webhook providers solve this with HMAC signatures (Hash-based Message Authentication Code). The idea is elegant: when you register your webhook URL, you also set a shared secret — a random string that only you and the provider know. When the provider sends a webhook, it signs the raw payload with that secret using a hashing algorithm, then includes that signature in a request header. When you receive the webhook, you independently compute the expected signature and compare it to what was sent. If they match, the payload is genuine.
Let's implement HMAC validation. GitHub's webhook format is a good reference — it sends a header called X-Hub-Signature-256 with a sha256= prefix:
# webhook_receiver.py (updated)
from flask import Flask, request, jsonify
import hashlib
import hmac
import json
import os
from dotenv import load_dotenv
load_dotenv()
app = Flask(__name__)
WEBHOOK_SECRET = os.environ.get("WEBHOOK_SECRET", "your-shared-secret-here")
def verify_signature(payload_bytes: bytes, signature_header: str, secret: str) -> bool:
"""
Verify that the webhook payload matches the provided HMAC signature.
Returns True if valid, False otherwise.
"""
if not signature_header:
return False
# The signature header looks like: "sha256=abcdef1234..."
if not signature_header.startswith("sha256="):
return False
received_signature = signature_header[7:] # Strip the "sha256=" prefix
# Compute expected signature using our shared secret
expected_signature = hmac.new(
key=secret.encode('utf-8'),
msg=payload_bytes,
digestmod=hashlib.sha256
).hexdigest()
# Use hmac.compare_digest to prevent timing attacks
return hmac.compare_digest(expected_signature, received_signature)
@app.route('/webhooks/support', methods=['POST'])
def handle_support_webhook():
payload_bytes = request.data
signature_header = request.headers.get('X-Hub-Signature-256', '')
if not verify_signature(payload_bytes, signature_header, WEBHOOK_SECRET):
print("Webhook signature validation FAILED")
return jsonify({"error": "Invalid signature"}), 401
try:
payload = json.loads(payload_bytes)
except json.JSONDecodeError:
return jsonify({"error": "Invalid JSON"}), 400
print(f"Valid webhook received: ticket_id={payload.get('ticket_id')}")
return jsonify({"status": "received"}), 200
if __name__ == '__main__':
app.run(port=5000, debug=True)
Warning
Notice the use of hmac.compare_digest() instead of a simple == comparison. This prevents timing attacks, where a malicious actor could figure out your secret by measuring how long your comparison takes. compare_digest always takes the same amount of time regardless of where strings differ. This is not paranoia — it's standard security practice.
For testing, you can generate a valid signed request with this helper script:
# generate_test_request.py
import hashlib
import hmac
import json
import requests
SECRET = "your-shared-secret-here"
URL = "http://localhost:5000/webhooks/support"
payload = {
"ticket_id": "T-1042",
"priority": "high",
"subject": "Cannot access my account",
"body": "I have been locked out for 3 days. This is very urgent.",
"customer_email": "alex.torres@example.com"
}
payload_bytes = json.dumps(payload).encode('utf-8')
signature = hmac.new(
key=SECRET.encode('utf-8'),
msg=payload_bytes,
digestmod=hashlib.sha256
).hexdigest()
response = requests.post(
URL,
data=payload_bytes,
headers={
"Content-Type": "application/json",
"X-Hub-Signature-256": f"sha256={signature}"
}
)
print(f"Status: {response.status_code}")
print(f"Response: {response.json()}")
Now for the interesting part. Once you've validated a webhook payload, you want to pass the data to an LLM and do something useful with it. For our customer support scenario, we'll have the LLM:
We want structured output from the LLM — not free-form text — so we can reliably use the classification downstream.
# llm_pipeline.py
from openai import OpenAI
import json
import os
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
def process_support_ticket(ticket: dict) -> dict:
"""
Takes a support ticket payload and returns LLM-generated classification
and draft response.
"""
subject = ticket.get("subject", "")
body = ticket.get("body", "")
priority = ticket.get("priority", "normal")
system_prompt = """You are a customer support AI assistant. When given a support ticket,
you must respond with a valid JSON object (and nothing else) containing exactly these fields:
{
"category": one of ["account_access", "billing", "technical_bug", "feature_request", "other"],
"urgency_score": integer from 1-10 (10 being most urgent),
"escalate_to_human": boolean (true if the issue requires a human agent),
"draft_response": a professional, empathetic reply to the customer (2-4 sentences),
"internal_note": a brief note for the support team explaining your assessment
}
Base your urgency score on both the stated priority and the content of the message."""
user_message = f"""Support Ticket:
Subject: {subject}
Priority: {priority}
Message: {body}
Please classify and draft a response."""
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_message}
],
temperature=0.3, # Lower temperature for more consistent, professional output
response_format={"type": "json_object"} # Force JSON output
)
result_text = response.choices[0].message.content
return json.loads(result_text)
Now we wire this into the webhook receiver. Here's where the asynchronous concern becomes real. The LLM call might take 3-10 seconds. External services expect a 200 response in under 5 seconds. We need to acknowledge receipt immediately and process in the background.
Python's threading module gives us a quick solution for this pattern:
# webhook_receiver.py (final version)
from flask import Flask, request, jsonify
from llm_pipeline import process_support_ticket
import hashlib
import hmac
import json
import os
import threading
from dotenv import load_dotenv
load_dotenv()
app = Flask(__name__)
WEBHOOK_SECRET = os.environ.get("WEBHOOK_SECRET", "your-shared-secret-here")
def verify_signature(payload_bytes: bytes, signature_header: str, secret: str) -> bool:
if not signature_header or not signature_header.startswith("sha256="):
return False
received_signature = signature_header[7:]
expected_signature = hmac.new(
key=secret.encode('utf-8'),
msg=payload_bytes,
digestmod=hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected_signature, received_signature)
def handle_ticket_async(ticket: dict):
"""Runs in a background thread — does the actual LLM processing."""
ticket_id = ticket.get("ticket_id", "unknown")
print(f"[{ticket_id}] Starting LLM processing...")
try:
result = process_support_ticket(ticket)
# In a real system, you'd write this to a database,
# call another API, trigger a Slack notification, etc.
print(f"[{ticket_id}] LLM Result:")
print(json.dumps(result, indent=2))
if result.get("escalate_to_human"):
print(f"[{ticket_id}] ⚠️ ESCALATION REQUIRED — urgency score: {result['urgency_score']}")
except Exception as e:
print(f"[{ticket_id}] Error during LLM processing: {e}")
@app.route('/webhooks/support', methods=['POST'])
def handle_support_webhook():
payload_bytes = request.data
signature_header = request.headers.get('X-Hub-Signature-256', '')
if not verify_signature(payload_bytes, signature_header, WEBHOOK_SECRET):
return jsonify({"error": "Invalid signature"}), 401
try:
payload = json.loads(payload_bytes)
except json.JSONDecodeError:
return jsonify({"error": "Invalid JSON"}), 400
# Spin up background thread for LLM processing
# We return 200 immediately — the work happens asynchronously
thread = threading.Thread(target=handle_ticket_async, args=(payload,))
thread.daemon = True
thread.start()
return jsonify({
"status": "received",
"ticket_id": payload.get("ticket_id")
}), 200
if __name__ == '__main__':
app.run(port=5000, debug=True)
Run python webhook_receiver.py, then fire the test request generator from earlier. You'll see your Flask server immediately return 200, then seconds later print the LLM's classification and draft response.
Note
Using threading works well for low-to-moderate volume. If you're processing hundreds of webhooks per minute, you'll want a proper task queue like Celery with Redis, or a cloud function. For learning purposes and early-stage production, threads are fine. For more on production deployment patterns, see Deploying LLM Applications: API Design and Infrastructure.
LLM calls fail. Networks hiccup. Rate limits get hit. Your webhook pipeline needs to handle this without silently dropping events.
The key principle: separate acknowledgment from processing. You've already done that with threads. Now add retry logic and proper error handling inside the background processor:
# llm_pipeline.py (with retry logic)
import time
from openai import OpenAI, RateLimitError, APITimeoutError
import json
import os
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
def process_support_ticket(ticket: dict, max_retries: int = 3) -> dict:
subject = ticket.get("subject", "")
body = ticket.get("body", "")
priority = ticket.get("priority", "normal")
system_prompt = """You are a customer support AI assistant...""" # (same as before)
user_message = f"Subject: {subject}\nPriority: {priority}\nMessage: {body}"
for attempt in range(max_retries):
try:
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_message}
],
temperature=0.3,
response_format={"type": "json_object"},
timeout=15 # Don't wait forever
)
return json.loads(response.choices[0].message.content)
except RateLimitError:
wait_time = 2 ** attempt # Exponential backoff: 1s, 2s, 4s
print(f"Rate limited. Waiting {wait_time}s before retry {attempt + 1}/{max_retries}")
time.sleep(wait_time)
except APITimeoutError:
print(f"API timeout on attempt {attempt + 1}/{max_retries}")
if attempt == max_retries - 1:
raise
except json.JSONDecodeError as e:
print(f"LLM returned invalid JSON: {e}")
raise # Don't retry malformed responses — the prompt needs fixing
raise RuntimeError(f"Failed after {max_retries} attempts")
For a deeper dive on this topic, the lesson on Handling LLM Errors, Timeouts, and Rate Limits in Python Applications covers exponential backoff and fallback strategies in much more detail.
Tip
For production systems, consider logging every webhook event to a database before processing — including the raw payload. If your LLM pipeline crashes, you can replay the event later without asking the sender to resend it. This is called an event log or inbox table pattern.
Build a webhook receiver that simulates a GitHub push notification triggering a code review assistant.
Scenario: When a developer pushes code, your system receives a webhook with the commit message and a list of changed files. The LLM should evaluate whether the commit message is descriptive enough and flag any files that might need extra review attention (e.g., files named auth.py, payment.py, or config.py).
Step 1: Create github_webhook.py with a route at /webhooks/github-push.
Step 2: Accept a payload with this structure:
{
"commit_id": "a3f8c12",
"commit_message": "fix stuff",
"author": "jamie.chen",
"changed_files": ["auth/login.py", "utils/helpers.py", "config/settings.py"],
"branch": "main"
}
Step 3: Write an LLM pipeline function that returns structured JSON with:
message_quality_score (1-5)message_feedback (what could be improved)high_risk_files (list of sensitive files from changed_files)review_recommended (boolean)Step 4: Add HMAC signature verification using the header X-GitHub-Signature.
Step 5: Use threading to process asynchronously and return 200 immediately.
Bonus: Add logging that writes each received webhook and its LLM result to a local webhook_log.json file (append-only).
"My webhook keeps getting retried even though I'm processing it." You're probably doing the LLM processing synchronously before returning 200. The external service waits, times out, and retries. Move your LLM call to a background thread and return 200 immediately after validation.
"Signature validation always fails."
Almost always caused by Flask parsing the body before you read it. HMAC signatures are computed on the raw bytes. Use request.data (which gives you raw bytes) rather than request.get_json() before computing the signature. Only parse JSON after validation passes.
"I'm getting different results each time for similar tickets."
Lower your temperature parameter. For classification tasks, values between 0.1 and 0.4 produce much more consistent output than the default of 1.0. When you need reliable structured output, consistency beats creativity. For more on managing this, see the lesson on Prompt Engineering Fundamentals: System Prompts, Few-Shot Examples, and Temperature Control.
"The LLM sometimes returns invalid JSON despite my instructions."
Add response_format={"type": "json_object"} to your OpenAI API call — this enforces JSON output at the API level. As a belt-and-suspenders move, wrap json.loads() in a try/except and log the raw response when it fails so you can debug your prompt.
"ngrok URL works in testing but I need a real deployment." ngrok is for development only. For production, deploy your Flask app behind a proper web server (gunicorn + nginx) or use a cloud function (AWS Lambda, Google Cloud Functions). Your webhook URL needs to be stable and publicly accessible. Consider reading about securing your API keys and authentication secrets before moving to production — your WEBHOOK_SECRET and OPENAI_API_KEY need to live in environment variables, not in your code.
"I want to build more complex pipelines triggered by webhooks." Once you have events flowing in reliably, you can extend the pipeline significantly — adding retrieval from a knowledge base, chaining multiple LLM calls, or using function calling to take actions. The lesson on Function Calling and Tool Use with LLMs: Building Intelligent Agents shows how to give your LLM the ability to actually do things in response to events, not just analyze them.
You've built a complete webhook integration pipeline from scratch. Let's recap what that involved:
This pattern — event in, validate, acknowledge, process asynchronously, act on result — is the backbone of event-driven AI automation. Once you've internalized it, you can connect almost any external system to an LLM pipeline.
Where to go from here:
For production deployments, you'll want to think about observability — knowing when things go wrong before your users tell you. The lesson on Implementing LLM Observability: Tracing, Logging, and Monitoring Requests in Production covers exactly this. You should also think about more sophisticated pipeline orchestration once your webhook triggers more than a single LLM call — Building AI Workflows with LangChain and LlamaIndex gives you a framework for chaining steps reliably. And if you're processing many webhooks concurrently, the patterns in Orchestrating Parallel LLM Calls: Batching, Concurrency, and Async Patterns for High-Throughput Production Pipelines will help you scale without blowing up your API costs.
The external world is constantly generating events. Now you know how to catch them and put AI to work on them in real time.