Calendly Webhook Debugging Guide

Calendly webhooks are a powerful mechanism for automating workflows around scheduled events. Whether you're integrating Calendly with a CRM, a marketing automation platform, or a custom internal tool, webhooks are how you get real-time notifications when an invitee schedules, reschedules, or cancels an event. However, as with any asynchronous communication, debugging Calendly webhooks can sometimes feel like trying to catch smoke. This guide will walk you through common issues, best practices, and how tools like Hookpeek can streamline your debugging process.

Understanding Calendly Webhooks

Before diving into debugging, let's briefly recap how Calendly webhooks operate. When a specific event occurs in your Calendly account (e.g., invitee.created, invitee.canceled, invitee.rescheduled), Calendly sends an HTTP POST request to a URL you've configured. This request contains a JSON payload detailing the event and the associated invitee and event information.

Key aspects: * Event Types: You select which events trigger a webhook. Common ones include invitee.created, invitee.canceled, and invitee.rescheduled. * Payload Structure: The JSON payload typically includes an event_type field and a payload object containing details about the event and the invitee. For instance, you'll often find payload.event.uri, payload.event.start_time, payload.invitee.email, and payload.invitee.status. * Signature Verification: Calendly includes an X-Calendly-Signature header. This is a HMAC-SHA256 signature generated using your webhook's signing_key and the request body. You should always verify this signature to ensure the request genuinely came from Calendly and hasn't been tampered with. * Configuration: Webhooks are set up in your Calendly Admin Center under "Integrations" -> "Webhooks." Here, you specify the target URL and the events you want to subscribe to.

Common Calendly Webhook Debugging Scenarios

Debugging webhooks usually falls into a few categories. Let's tackle them systematically.

Scenario 1: The Webhook Isn't Firing at All

If your application isn't receiving any requests, here's what to check:

  • Is the URL Correct? Double-check the webhook URL configured in Calendly. A typo, a missing https://, or an incorrect port can prevent delivery.
  • Is the Event Type Selected? Ensure you've subscribed to the correct event types in Calendly's webhook settings. If you're expecting invitee.created but only invitee.canceled is checked, you won't get the former.
  • Is Your Endpoint Publicly Accessible? Calendly needs to reach your server over the internet.
    • If you're developing locally, you'll need a tunneling tool like ngrok or localtunnel to expose your local server to the internet. For example, ngrok http 8000 will give you a public URL for your local port 8000.
    • If your application is deployed, check for firewall rules, security groups, or load balancer configurations that might be blocking incoming POST requests to your webhook endpoint.
    • Ensure your server is actually running and listening on the specified port.
  • Calendly's Status: Occasionally, Calendly itself might experience issues. Check their status page for any outages.
  • Calendly's Webhook Logs: Calendly provides a basic log of webhook attempts within the "Webhooks" section of the Admin Center. While not as detailed as a full debugger, it can tell you if Calendly tried to send the request and what the response status was (e.g., 200 OK, 500 Internal Server Error).

Scenario 2: The Webhook Fired, But Your Application Didn't Process It Correctly

This is where the real debugging begins. Your server received the request, but something went wrong in your application logic.

  • Server-Side Logs: The first step is always to check your application's logs. Are there any errors, exceptions, or warnings when the webhook request comes in? Look for HTTP 5xx errors that indicate server-side problems.

  • Payload Parsing Issues: Webhook payloads are JSON. Incorrectly parsing the JSON can lead to KeyError or TypeError exceptions.

    • Example 1: Basic Flask Endpoint for Receiving Webhooks ```python from flask import Flask, request, jsonify import hmac import hashlib import os

      app = Flask(name)

      Get your Calendly signing key from environment variables or a secure config

      CALENDLY_SIGNING_KEY = os.environ.get("CALENDLY_SIGNING_KEY")

      @app.route('/webhook/calendly', methods=['POST']) def calendly_webhook(): if not request.is_json: print("Webhook request is not JSON.") return jsonify({"message": "Request must be JSON"}), 400

      data = request.json
headers = request.headers

# --- Signature Verification (Crucial!) ---
if CALENDLY_SIGNING_KEY:
    signature_header = headers.get('X-Calendly-Signature')
    if not signature_header:
        print("Missing X-Calendly-Signature header.")
        return jsonify({"message": "Signature header missing"}), 401

    # The signature header format is 't=timestamp,v1=signature'
    # We need to extract the v1 signature part
    try:
        parts = signature_header.split(',')
        timestamp_str = parts[0].split('=')[1]
        signature = parts[1].split('=')[1]
    except IndexError:
        print(f"Malformed X-Calendly-Signature header: {signature_header}")
        return jsonify({"message": "Malformed signature header"}), 401

    # Construct the signed payload: timestamp.json_payload
    signed_payload = f"{timestamp_str}.{request.get_data(as_text=True)}"
    expected_signature = hmac.new(
        CALENDLY_SIGNING_KEY.encode('utf-8'),
        signed_payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected_signature, signature):
        print("Webhook signature verification failed.")
        return jsonify({"message": "Invalid signature"}), 401
    else:
        print("Webhook signature verified successfully.")
else:
    print("CALENDLY_SIGNING_KEY not configured. Skipping signature verification.")

# --- Process the Webhook ---
event_type = data.get('event_type')
invitee_email = data.get('payload', {}).get('invitee', {}).get('email')
event_name = data.get('payload', {}).get('event', {}).get('name')

print(f"Received Calendly webhook: {event_type}")
print(f"Invitee Email: {invitee_email}")
print(f"Event Name: {event_name}")
# Add your custom processing logic here

return jsonify({"message": "Webhook received successfully"}), 200

      if name == 'main': # For local development, set CALENDLY_SIGNING_KEY in your environment # e.g., export CALENDLY_SIGNING_KEY="your_calendly_signing_key" app.run(port=8000) ``` This example demonstrates how to receive a webhook and the critical step of signature verification. Without a tool to inspect the exact incoming request, debugging issues like malformed JSON or incorrect headers can be incredibly difficult.

  • Signature Verification Failures: This is a very common issue.

    • Is your CALENDLY_SIGNING_KEY correct and matching the one in Calendly?
    • Are you correctly extracting the timestamp and signature from the X-Calendly-Signature header?
    • Are you constructing the signed_payload string exactly as Calendly specifies (timestamp followed by a dot, then the raw