Welcome to the Acuity Scheduling
Developer Hub!

Here you'll find guides and documentation to help you start working with Acuity as quickly as possible, as well as support if you get stuck. Let's jump right in!

Webhooks notify a URL when an appointment is scheduled, canceled, or rescheduled. You c an create webooks statically within your Acuity account or dynamically via API in Acuity.

Static Webhooks

Under Integrations set the Webhook integration with the URL to be notified on changes to appointments. The URL must be to port 443 or 80.

Webhook requests are application/x-www-form-urlencoded POST requests with these variables:

  • action either scheduled rescheduled canceled or changed depending on the action that initiated the webhook call
  • id the ID for the appointment, get the appointment details for through the get appointment API call
  • calendarID the ID of the calendar for the appointment
  • appointmentTypeID the ID of the type of the appointment

The different actions:

  • scheduled is called once when an appointment is initially booked
  • rescheduled is called when the appointment is rescheduled to a new time
  • canceled is called whenever an appointment is canceled
  • changed is called when the appointment is changed in any way. This includes when it is initially scheduled, rescheduled, or canceled, as well as when appointment details such as e-mail address or intake forms are updated.

Dynamic Webhooks

This new feature allows you to create new Webhook subscriptions through the Webhooks API. Click here to learn all details.

Verifying Webhook Requests

Webhook notifications are signed by Acuity using your API key, so you can verify that a notification is from Acuity. First compute the base64 HMAC-SHA256 signature of the notification using the request's body as the message and your API key as the shared secret. Then compare this signature to the request header X-Acuity-Signature . If they match, the notification is authentic.

<?php
// Get hash of message using shared secret:
$body = file_get_contents('php://input');
$hash = base64_encode(hash_hmac('sha256', $body, $secret, true));

// Compare the two:
if ($hash !== $_SERVER['HTTP_X_ACUITY_SIGNATURE']) {
	throw new Exception('This message was forged!');
}
// Get hash of message using shared secret:
var hasher = crypto.createHmac('sha256', secret);
hasher.update(buf.toString());
var hash = hasher.digest('base64');

// Compare hash to Acuity signature:
if (hash !== req.header('X-Acuity-Signature')) {
	throw new Error('This message was forged!');
}
require 'openssl'
require 'base64'

def verify_message_signature(secret, body, signature)
  hash = Base64.encode64(OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), secret, body))
  if hash.strip() != signature
    raise 'This message was forged!'
  end
end
POST https://example.com/webhook-callback

action=changed&id=13&calendarID=1&appointmentTypeID=13

Simulate Acuity Webhooks

You can use curl to simulate Acuity webhooks:

curl -d "action=changed&id=1&calendarID=1&appointmentTypeID=1" "https://example.com/webhook-callback"

Webhook Retries

Webhook calls are retried with exponential backoff over a 24 hour period. Acuity will stop attempting if there is not a successful response after 24 hours.

Retry Number
Interval

1

2 seconds

2

30 seconds

3

1 minute

4

5 minutes

5

10 minutes

6

15 minutes

7

30 minutes

8

1 hour

9

12 hours

Webhooks