# 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).

```javascript
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/acuity-scheduling-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/acuity-scheduling-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/acuity-scheduling-webhooks/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](https://github.com/hookdeck/webhook-skills/blob/main/skills/acuity-scheduling-webhooks/references/overview.md) and [Acuity's webhook documentation](https://developers.acuityscheduling.com/docs/webhooks).

## Environment Variables

```bash
# 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

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/acuity-scheduling-webhooks/references/overview.md) - What Acuity webhooks are, actions, payload
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/acuity-scheduling-webhooks/references/setup.md) - Static and dynamic webhook configuration, finding your API key
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/acuity-scheduling-webhooks/references/verification.md) - Signature verification details and gotchas