Developer documentation
Back to index

Webhooks

Webhooks are user-defined callbacks that inform other applications or websites about events happening on your SuperSaaS account in near real-time. They can be used to extend the functionality of your schedule, for example, by subscribing new users to a mailing list or by sending you a chat message for a changed appointment.

Automatically configuring webhooks

You can use either Zapier.com or Integromat.com to interactively create webhooks between hundreds of well-known websites and SuperSaaS, without the need for programming.

Read more: Automatically configure webhooks using Zapier or Integromat

Manually configuring webhooks

Please note that this feature is only available to subscribers. You can try it out for a week by clicking the button “Start free trial” on the webhooks screen.

You can manually create and update webhooks on the Webhooks screen inside your account. A webhook sends data, so it requires that a web service is available on the other side to receive the data. Typically the other side is a script or application that you create, but it can also be third party website that the webhook connects to.

Creating a webhook without the use of Zapier or Integromat requires some web development skills. The remainder of this page contains information for programmers looking to add a webhook to send information to their own application, or who want to program their own interface between SuperSaaS and another site.

Customizing the message that a webhook sends

By default a webhook sends across all relevant fields encoded as JSON. Note that if an object has an attached custom form then that form is also included. You can change this to send no data at all, or to send data you define yourself. For example, you may want to include some kind of API key or authentication in the message.

After you create a new webhook you will automatically arrive on a screen where you can edit the contents of the “payload”, the message the webhook sends. If you click Custom you will see a JSON editor that allows you to add and remove specific fields. The bottom of that screen lists all available “magic words” that are replaced when the message is generated. The magic words change depending on the fields that are enabled for that object.

Testing a webhook

A good website to help you to debug a webhook is RequestBin. The service supplies you with a link that you can use as the target URL so you can monitor exactly what data is being sent across.

You can also find a Test link on the edit screen of the webhook that enables you to fire off a hook manually and modify the outgoing message. This allows you to modify an outgoing call to mimic, for example, a failed payment without actually having to generate such an event on your schedule.

The test message should fire on average about 5 seconds after it has been created. If the receiving side responds with a status code that is not “OK” (status code outside the range 200 to 300) the message will be attempted again at increasing intervals. After 10 failures the message will be deleted and if a hook has more than 5 failed messages it will become inactive until manually reactivated on the webhook screen. If the receiving end replies with a “410 Gone” status code the webhook will be removed right away.

Active message queue

If the message from a webhook cannot be sent right away you will see a link to view a list of all pending messages. The message queue screen will indicate the next attempt for the message and clicking on the spyglass icon will show the contents of the message.

Supported Triggers

There are several different events that you can monitor. Some events can be monitored either for a “new” event, or a “changed” event. The “changed” event includes every change, so it also fires on “new” and “delete”. So if you configure both a “New user” and a “Changed user” then both hooks will fire when a new user signs up. Note that if you’ve configured your schedule to not require signup then you would never see a “New user” trigger, only a “New appointment” trigger.

TriggerCaused by…
New userFires when a user registers for your account
Changed userFires when the user updates his registration information, or the administrator does it for him.
New appointmentFires when a user, or the admin, makes an appointment on the specified schedule.
Changed appointmentFires on all possible changes to an appointment, including “New”, “Delete”, “Placement from waiting list”, “Payment received”, etc. (See the full list below)
New stand-alone formFires when a stand-alone form is filled out. Note that it does not trigger when a form is attached to an appointment, instead that would trigger the appointment webhook.
Updated stand-alone formFires upon any change to a stand-alone form (integrated forms would trigger a “Changed appointment” or “Changed user”)
Send mail‘Fires on all emails sent from your account, including “Lost password” mails etc. Useful to send mail through your own server. Email will no longer be sent by us if this webhook is active. More information.
Reminder
Follow up
Fires on Reminders or Follow ups. The reminder or follow up will no longer be sent by us if its webhook is active.

Event and role fields

You may want to filter events, for example, to only send a message if an appointments is deleted by a user and not by the administrator. The “event” and “role” fields included in the default fields can be used to construct such a filter, see the tables below for the possible values these fields can contain.

TriggerPossible values of the “event” field
New usernew
Changed usernew, change, delete
New appointmentcreate
Changed appointmentcreate, edit, place, pending, destroy, restore, approve, revert
New formnew
Changed formnew, change, delete, restore
Reminder / Follow upreminder, follow_up

“Role” fieldWho triggered the event…
0AnonymousNot logged in
1Logged in with a shared password
2Validated using an IP range check
3Regular user
4Superuser
5Administrator or Reseller
7System or Payment gateway

Status field

When creating or changing an appointment that includes payment, the fields “status” and “status message” allow you to further narrow down to specific events using the list of all possible status codes. For example, you could set a filter to only act on messages for appointments that have been refunded.

Note that appointments and users created through our API by default do not trigger the corresponding webhook. You can change that behavior by adding webhook=true as a parameter to the API call.