Integrate Calendly with OpenClaw by: (1) choosing authentication (a user OAuth flow for multi-user installs or a Personal Access Token for a single account); (2) storing credentials and tokens in ClawHub as secrets; (3) running an external, hardened webhook receiver (a web service you control) that validates Calendly webhooks, normalizes events, and then explicitly invokes your OpenClaw skill (or enqueues work your skill will pick up); and (4) using Calendly REST APIs for lookups and webhooks while keeping state, retries, and long-running work outside the agent runtime. This makes the integration explicit, auditable, and safe — the agent never “magically” reads Calendly; your code does, with explicit credentials and verified webhooks.

 High-level flow and responsibilities 

• Calendly: emits webhooks for invites/events and exposes REST APIs (for scheduled events, invitees, event types).
• Your external service (webhook receiver): receives and validates Calendly webhooks, fetches additional data from Calendly APIs if needed, normalizes payloads, enqueues or forwards work to OpenClaw.
• ClawHub: stores credentials (OAuth client secrets or API keys) and configures the OpenClaw skill. ClawHub is the place you register/configure the skill and its secrets — actual HTTP flows and webhook handling happen in your service.
• OpenClaw agent / skill runtime: runs your skill code when triggered; keep it stateless where possible and move persistence/queues outside the agent for reliability and scale.

 Step-by-step integration plan (practical) 

• Decide auth model
  • Use OAuth2 if multiple Calendly users will connect (each user grants access to their account).
  • Use a Personal Access Token (PAT) if you only need a single Calendly account (faster to prototype).
• Store credentials in ClawHub
  • Store client_id/client_secret or PAT in ClawHub secrets (do not hard-code in source or the agent image).
• Implement an external webhook receiver
  • Host a stable HTTPS endpoint (examples below) to receive webhooks from Calendly.
  • Validate the webhook signature using the secret provided by Calendly (verify HMAC or the signature method specified in Calendly docs).
  • On valid webhook, optionally call Calendly REST API to fetch richer details, normalize the payload, then trigger the OpenClaw skill explicitly.
• Register webhook with Calendly
  • Create a webhook subscription via Calendly REST API (POST to their webhook/subscriptions endpoint) using your stored token.
  • Choose the exact events you need (e.g., invitee.created, invitee.canceled) so you only receive necessary traffic.
• Triggering the skill
  • Two safe patterns:
    • Webhook handler calls a ClawHub-configured skill endpoint (HTTP request or ClawHub API) to run the agent logic for that event.
    • Webhook handler enqueues a job in your external queue (Redis, SQS). A separate worker (or the agent) dequeues and processes it. Prefer this for long-running or retry-critical work.
• Design for failure and scale
  • Keep state and retry logic outside the agent (database + queue + worker). Let the agent be ephemeral for compute steps.
  • Record idempotency keys so retries (Calendly retries deliveries) don’t produce duplicate actions.

 Example: secure webhook receiver (Node.js/Express) 

• Below is a minimal Express example that reads the raw body, computes an HMAC, and compares with a header you configure. Replace SIGNATURE\_HEADER and verify the hashing method against Calendly docs (Calendly signs requests — check exact header name and algorithm before deploy).

<b>//</b> app.js - minimal webhook receiver with raw body parsing and HMAC verification
const express = require('express');
const crypto = require('crypto');

const app = express();

/<b>//</b> Use raw body for exact HMAC verification
app.use('/webhooks/calendly', express.raw({ type: 'application/json' }));

app.post('/webhooks/calendly', (req, res) => {
  const rawBody = req.body; <b>//</b> Buffer
  const secret = process.env.CALENDLY_WEBHOOK_SECRET; <b>//</b> set in ClawHub or env
  const sigHeaderName = process.env.SIGNATURE_HEADER || 'x-calendly-signature'; <b>//</b> configurable

  if (!secret) return res.status(500).send('Secret not configured');

  <b>//</b> compute HMAC-SHA256; confirm algorithm with Calendly docs
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');

  const received = (req.headers[sigHeaderName] || '').trim();

  <b>//</b> constant-time compare
  function safeEqual(a, b) {
    try {
      const bufA = Buffer.from(a, 'utf8');
      const bufB = Buffer.from(b, 'utf8');
      if (bufA.length !== bufB.length) return false;
      return crypto.timingSafeEqual(bufA, bufB);
    } catch (e) {
      return false;
    }
  }

  if (!safeEqual(expected, received)) {
    return res.status(401).send('invalid signature');
  }

  <b>//</b> Parse JSON after signature verified
  const payload = JSON.parse(rawBody.toString('utf8'));

  <b>//</b> Normalize event and either call the OpenClaw skill or enqueue work
  // Example: call your job API
  // fetch('https://your.backend/jobs', { method: 'POST', body: JSON.stringify({ type: 'calendly.event', data: payload }), headers: { 'Content-Type': 'application/json' } });

  res.status(200).send('ok');
});

app.listen(process.env.PORT || 3000);

 Example: create a Calendly webhook subscription (curl, REST) 

• The Calendly REST API is standard HTTPS with a Bearer token. Below is a typical example; confirm required body fields (scope, events, organization) against Calendly API docs for the exact JSON shape.

<b>//</b> Create a webhook subscription - replace $TOKEN and the URL
curl -X POST "https://api.calendly.com/webhook_subscriptions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your.example/webhooks/calendly",
    "events": ["invitee.created", "invitee.canceled"]
  }'

 Example: fetch a scheduled event (REST) 

• Use Calendly REST to fetch details if the webhook payload is summary-only. Replace {event\_uuid} with the ID from the webhook.

<b>//</b> Fetch event details
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.calendly.com/scheduled_events/{event_uuid}"

 OAuth note (when you need per-user installs) 

• Implement the standard OAuth2 redirect -> authorize -> token exchange flow. Store refresh tokens securely in ClawHub or your external backend, and refresh before expiry.
• Scopes: request only the Calendly scopes you need (webhook manage, read scheduled events, etc.). Verify the exact scope strings in Calendly docs.
• After OAuth completion, create webhook subscriptions on behalf of that user (if your app needs webhooks per user) — or instruct users to enable webhooks if Calendly requires it in the app flow.

 How to wire this to an OpenClaw skill (explicit, reliable patterns) 

• Direct HTTP trigger: configure your skill in ClawHub so it exposes (or is reachable from) an HTTP endpoint. Your webhook handler calls that endpoint with a normalized payload. The call includes authentication (a ClawHub-generated API key or signed request stored in ClawHub secrets).
• Queue-based: webhook handler enqueues an event to a durable queue (SQS, Redis stream). A worker process (which can be under your control and authenticate via ClawHub) pulls jobs and calls the OpenClaw skill. This is the preferred pattern for retries and long-running workflows.
• State and persistence: store event state, idempotency keys, and retry metadata in an external DB (Postgres, DynamoDB). Do not rely on the agent runtime for persistent storage.

 Deployment, security, and operational checklist 

• Secrets: keep Calendly tokens and webhook secrets in ClawHub secret storage or a secrets manager; never check them into source control.
• Least privilege: request minimal Calendly scopes and rotate tokens periodically.
• Webhook validation: always validate signatures. Reject malformed or unsigned requests.
• Idempotency: store an idempotency key per Calendly event ID to avoid duplicate processing.
• Retries: implement retry with backoff for transient failures and return appropriate HTTP status codes so Calendly can retry delivery, or rely on your queue for retries.
• Observability: log incoming webhook headers, body hashes, verification results, API errors, and ClawHub/agent invocation responses so you can trace from Calendly delivery to skill execution.
• Monitoring: track webhook delivery status in Calendly (if provided) and health-check your webhook receiver endpoint externally.

 Debugging checklist (when things fail) 

• Confirm webhook subscription exists and points to the correct public HTTPS URL.
• Check webhook delivery logs in Calendly (status codes, error messages) and your service logs for signature failures or parse errors.
• Verify the signature algorithm and header name against Calendly docs; ensure you compute HMAC over the exact raw bytes Calendly sent.
• Confirm your stored token is valid and has required scopes; if using OAuth, check refresh/expiration flows.
• Inspect API responses when creating subscription or fetching events — log the full response body and HTTP status for diagnosis.
• Check idempotency keys to ensure you're not ignoring events as duplicates incorrectly.
• If the OpenClaw skill is not invoked, ensure your webhook handler successfully calls the skill and authenticate those calls with a ClawHub-managed secret or service account token.