Add Webhook Subscription

Creates a webhook subscription to receive real-time notifications when specific events occur in your Calendly account, such as new meeting bookings or cancellations.

Common Properties

• Name - The custom name of the node.
• Color - The custom color of the node.
• Delay Before (sec) - Waits in seconds before executing the node.
• Delay After (sec) - Waits in seconds after executing node.
• Continue On Error - Automation will continue regardless of any error. The default value is false.

info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs

• Client Id - (Optional) The unique client identifier returned by the Connect node. If not provided, you must supply Credentials directly.

• Webhook Url - (Required) The HTTPS URL where Calendly will send event notifications. This must be a publicly accessible endpoint that can receive POST requests.

• Organization Url - (Required) The Calendly organization URL (URI) to which the webhook subscription belongs. Format: https://api.calendly.com/organizations/XXXXXXXXXX

Options

• Credentials - (Optional) Calendly API Token credential for direct authentication. Use this if you're not using the Connect/Disconnect pattern.

• Events - (Required) The type of events to subscribe to:

  • All - Receive notifications for both created and canceled invitees
  • Create - Only receive notifications when new meetings are scheduled
  • Cancel - Only receive notifications when meetings are canceled

• User Url - (Optional) A specific user URL to scope the subscription to. If provided, only events for this user will trigger notifications. Format: https://api.calendly.com/users/XXXXXXXXXX

Output

• Result - An object containing the created webhook subscription details, including:
  • Webhook subscription URI and unique ID
  • Callback URL
  • Subscribed events list
  • Organization and user scope
  • Creation timestamp
  • State (active/disabled)
  • Retry configuration

How It Works

The Add Webhook Subscription node configures Calendly to send HTTP POST requests to your specified endpoint whenever monitored events occur. This enables real-time automation based on Calendly activity.

When executed, the node:

1. Uses either the Client ID from Connect or direct credentials
2. Validates the webhook URL and organization URL
3. Configures the event types to monitor (create, cancel, or both)
4. Makes a POST request to /webhook_subscriptions endpoint
5. Returns the webhook subscription details including the subscription ID

Webhook Events

Calendly will send POST requests to your Webhook URL when events occur:

Event: invitee.created

Triggered when someone books a meeting through your Calendly link.

Event: invitee.canceled

Triggered when a scheduled meeting is canceled.

Webhook Payload

When an event occurs, Calendly sends a POST request to your webhook URL with a JSON payload:

{
  "event": "invitee.created",
  "time": "2024-11-20T15:30:00.000000Z",
  "payload": {
    "event": "https://api.calendly.com/scheduled_events/XXXXXXXXXX",
    "invitee": "https://api.calendly.com/scheduled_events/XXXXXXXXXX/invitees/YYYYYYYYYY"
  }
}

Requirements

• A publicly accessible HTTPS endpoint to receive webhooks
• A valid Calendly organization URL (get from organization settings or API)
• For user-scoped webhooks: A valid user URL (get from Get Me node)
• Webhook endpoint must respond with HTTP 200-299 status code

Getting Organization URL

You can obtain your organization URL:

1. From the Get Me node response: result.resource.current_organization
2. From Calendly API: /users/me endpoint
3. From organization settings in Calendly dashboard

Error Handling

The node will return specific errors in the following cases:

ErrInvalidArg

• Webhook URL is empty or missing
• Organization URL is empty or missing
• Events option not selected
• Solution: Provide all required parameters

ErrInternal

• Network error connecting to Calendly API
• Webhook URL is not accessible or not HTTPS
• Organization URL is invalid or not accessible
• API authentication failed
• Rate limit exceeded
• Solution: Verify all URLs and credentials

Usage Examples

Example 1: Subscribe to All Events (Organization-Wide)

[Start]
  -> [Calendly Connect] (outputs: client_id)
  -> [Get Me] (outputs: result)
  -> [Add Webhook Subscription]
      - Webhook Url: "https://myapp.com/webhooks/calendly"
      - Organization Url: {{result.resource.current_organization}}
      - Events: "All"
  -> [Log] (message: "Webhook created: {{result.resource.uri}}")
  -> [Disconnect]
  -> [End]

Example 2: Subscribe to Only New Bookings

[Start]
  -> [Calendly Connect]
  -> [Get Me] (outputs: result)
  -> [Add Webhook Subscription]
      - Webhook Url: "https://myapp.com/calendly/new-booking"
      - Organization Url: {{result.resource.current_organization}}
      - Events: "Create"
  -> [Store Webhook ID] (for later deletion)
  -> [Disconnect]
  -> [End]

Example 3: User-Scoped Webhook

[Start]
  -> [Calendly Connect]
  -> [Get Me] (outputs: result)
  -> [Add Webhook Subscription]
      - Webhook Url: "https://myapp.com/calendly/user-events"
      - Organization Url: {{result.resource.current_organization}}
      - User Url: {{result.resource.uri}}
      - Events: "All"
  -> [Disconnect]
  -> [End]

Example 4: Cancellation Monitoring

[Start]
  -> [Calendly Connect]
  -> [Get Me] (outputs: result)
  -> [Add Webhook Subscription]
      - Webhook Url: "https://crm.company.com/calendly/cancellations"
      - Organization Url: {{result.resource.current_organization}}
      - Events: "Cancel"
  -> [Send Alert] (message: "Cancellation monitoring active")
  -> [Disconnect]
  -> [End]

Example 5: Multiple Webhooks for Different Events

[Start]
  -> [Calendly Connect]
  -> [Get Me] (outputs: result)

  -> [Add Webhook Subscription] (for creates)
      - Webhook Url: "https://myapp.com/booking-created"
      - Organization Url: {{result.resource.current_organization}}
      - Events: "Create"

  -> [Add Webhook Subscription] (for cancels)
      - Webhook Url: "https://myapp.com/booking-canceled"
      - Organization Url: {{result.resource.current_organization}}
      - Events: "Cancel"

  -> [Disconnect]
  -> [End]

Usage Notes

• Webhook URLs must use HTTPS (HTTP is not supported)
• Your endpoint must respond quickly (within 10 seconds) to avoid timeouts
• Calendly retries failed webhook deliveries with exponential backoff
• Maximum of 100 webhook subscriptions per organization
• Webhooks can be organization-scoped or user-scoped
• User-scoped webhooks only fire for that specific user's events

Best Practices

• Endpoint Security

  • Validate webhook signatures to ensure requests are from Calendly
  • Use HTTPS with valid SSL certificates
  • Implement IP whitelisting if possible

• Response Handling

  • Return HTTP 200-299 immediately upon receiving webhook
  • Process webhook data asynchronously to avoid timeouts
  • Implement idempotency to handle duplicate deliveries

• Error Recovery

  • Log all webhook deliveries for debugging
  • Monitor for failed deliveries in Calendly dashboard
  • Implement retry logic for processing failures

• Webhook Management

  • Store subscription IDs for later deletion
  • Document which webhooks are active and their purposes
  • Delete unused webhooks to avoid hitting limits
  • Use List Webhook Subscriptions to audit active webhooks

• Testing

  • Use tools like ngrok for local development
  • Test with actual Calendly events before production
  • Verify both create and cancel events if using "All"

Common Use Cases

1. CRM Integration

   • Automatically create CRM records when meetings are booked
   • Update deal stages based on meeting status

2. Team Notifications

   • Send Slack/Teams messages when meetings are scheduled
   • Alert managers of cancellations

3. Automated Follow-ups

   • Send confirmation emails after booking
   • Trigger email sequences for canceled meetings

4. Analytics and Reporting

   • Track booking patterns and trends
   • Generate reports on cancellation rates

5. Resource Management

   • Reserve meeting rooms automatically
   • Allocate resources based on meeting type

6. Multi-System Synchronization

   • Sync bookings to calendar systems
   • Update project management tools

Webhook Verification

To verify webhooks are from Calendly:

1. Calendly includes a signature in the webhook headers
2. Verify the signature using your webhook signing key
3. Check the timestamp to prevent replay attacks
4. Validate the event structure matches expected schema

Debugging Webhooks

If webhooks aren't being received:

1. Check URL Accessibility

   • Ensure the URL is publicly accessible
   • Verify HTTPS certificate is valid
   • Test with curl or Postman

2. Review Subscription

   • Use List Webhook Subscriptions to verify it exists
   • Check the subscription state (should be "active")

3. Monitor Logs

   • Check Calendly's webhook delivery logs
   • Review your endpoint's access logs

4. Test Events

   • Create a test booking to trigger webhooks
   • Verify event type matches subscription

Rate Limits

Creating webhook subscriptions counts toward API rate limits:

• Each subscription creation = 1 API request
• Maximum 100 subscriptions per organization
• Consider consolidating similar webhooks when possible

Response Structure

The Result output contains:

{
  "resource": {
    "uri": "https://api.calendly.com/webhook_subscriptions/XXXXXXXXXX",
    "callback_url": "https://myapp.com/webhooks/calendly",
    "created_at": "2024-11-20T10:30:00.000000Z",
    "updated_at": "2024-11-20T10:30:00.000000Z",
    "retry_started_at": null,
    "state": "active",
    "events": ["invitee.created", "invitee.canceled"],
    "scope": "organization",
    "organization": "https://api.calendly.com/organizations/BBBBBBBBBBBBBBBB",
    "user": null,
    "creator": "https://api.calendly.com/users/AAAAAAAAAAAAAAAA"
  }
}

Extract the subscription ID for deletion:

{{result.resource.uri}}