Webhooks: Connecting SuperSaaS to other websites
Webhooks are user-defined callbacks that inform other applications or websites about events happening on your SuperSaaS account in near real-time. A popular use is to send email via another server.
A few examples of how you can use a webhook:
- When a new user signs up on your SuperSaaS account subscribe him to a MailChimp mailing list
- When a user gets moved from a waiting list to a confirmed place send him an SMS message
- When a new user signs up send a PDF with your terms and conditions to his email address
- When a new appointment is made on a schedule generate an invoice in QuickBooks
- When a new appointment is made for a specific class, mark the Google Calendar of the teacher of that class
- When a customer changes his appointment send a notification to your customer support system
Automatically configure webhooks using Zapier.com
The website Zapier.com allows you to interactively create links between hundreds of well-known websites, including SuperSaaS, without the need for programming. Zapier offers a trial version and a free tier for small users.
It should be relatively straightforward to create “Zaps” from the pre-made examples, but you can find detailed information below if you want more fine grained control by filtering only certain events.
There are three event categories that you can monitor, and for each of those you can either monitor the “new” event, or the “change” event. Note that the “change” event includes every change, so it also fires on “new” and “delete”.
|New user||Fires when a user registers for your account|
|Changed user||Fires when the user updates his registration information, or the administrator does it for him.|
|New appointment||Fires when a user, or the admin, makes an appointment on the specified schedule.|
|Changed appointment||Fires 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 form||Fires 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 form||Fires upon any change to a stand-alone form (integrated forms would trigger a “changed appointment”)|
|Send mail||Fires on all emails sent from your account, including “Lost password” mails etc. Useful to send mail through your own server.|
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.
When you connect two services on Zapier it allows you to filter the events. Some examples of how you can use filters:
- Only send an SMS notification when someone is placed from a waiting list, not for every appointment change
- Only notify a teacher of a new booking if the class is taught by that teacher, ignore other bookings on the same schedule
- Only send a notification to management if the booking has a value of more than $100
When you create a new “Zap”, as they call it, the Zapier site will request an example object from SuperSaaS. The example object lists the available fields and some example content. The fields that the webhook sends are dependent on which fields are enabled in your account and whether a custom form is attached. The fields “trigger” and “role” are included with all triggers, except “Send mail”, and are useful way to filter events. For example, you could filter only triggers that contain the value “delete” in the field “event”.
|Trigger||Possible values of the “event” field|
|Changed user||new, change, delete|
|Changed appointment||create, edit, place, pending, destroy, restore, approve, revert|
|Changed form||new, change, delete, restore|
|“Role” field||Who triggered the event…|
|0||Anonymous||Not logged in|
|1||Logged in with a shared password|
|2||Validated using an IP range check|
|5||Administrator or Reseller|
|7||System or Payment gateway|
When creating or changing an appointment that includes payment, the field “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.
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.
Creating a webhook without the use of Zapier 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.
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.
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.