Agent skill

Acuity Scheduling Webhooks Skill

Receive and verify Acuity Scheduling webhooks. Use when setting up Acuity Scheduling webhook handlers, debugging X-Acuity-Signature verification, or handling appointment actions like scheduled, rescheduled, canceled, changed, and order.completed.

Install this skill

npx skills add hookdeck/webhook-skills --skill acuity-scheduling-webhooks

When to Use This Skill

How do I receive Acuity Scheduling webhooks?
How do I verify the X-Acuity-Signature header?
How do I handle scheduled, rescheduled, canceled, changed or order.completed webhooks?
Why is my Acuity Scheduling webhook signature verification failing?
How do I parse Acuity's form-encoded webhook body?

Verification (core)

Acuity signs the raw request body with HMAC-SHA256, base64 encoded, and sends it in the X-Acuity-Signature header. The key is your Acuity API key, not a separate webhook secret: the main admin's API key for static webhooks (Integrations settings), or your user's API key for webhooks created through the API. There is no timestamp in the signature. Acuity has no SDK verification helper, so verify manually, using the raw body (before any form parsing).

const crypto = require('crypto');

function verifyAcuitySignature(rawBody, signatureHeader, apiKey) {
  if (!signatureHeader) return false;
  const expected = crypto.createHmac('sha256', apiKey).update(rawBody).digest('base64');
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

The body is application/x-www-form-urlencoded (action, id, calendarID, appointmentTypeID). Parse it only after verifying. In Express, use express.raw({ type: '*/*' }) so the body is a raw Buffer whatever content type is sent.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Common Event Types

The event type is the action form field.

Action	Triggered When
`scheduled`	An appointment is initially booked (sent once)
`rescheduled`	An appointment is moved to a new time
`canceled`	An appointment is canceled
`changed`	Catch-all: any change, including schedule, reschedule, cancel, and detail or intake form updates
`order.completed`	A package, gift certificate or subscription order is completed

Using changed together with scheduled, rescheduled or canceled can produce duplicate requests. The payload carries only IDs; fetch the full appointment from the Acuity API using id.

For the full event reference, see references/overview.md and Acuity's webhook documentation.

Environment Variables

# Your Acuity API key (main admin's key for static webhooks, your user's key for API webhooks)
ACUITY_API_KEY=your_acuity_api_key_here

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 acuity-scheduling --path /webhooks/acuity-scheduling

Reference Materials

references/overview.md - What Acuity webhooks are, actions, payload
references/setup.md - Static and dynamic webhook configuration, finding your API key
references/verification.md - Signature verification details and gotchas