Hooks allow you to set up integrations which subscribe to certain events on vCita. When one of those events is triggered, we’ll send a HTTP POST payload to the hook’s configured URL.
1. Events
When configuring a hook, you choose which events you would like to receive payloads for and where to send them. Most common events are related to the lifecycle of objects in the vCita system - objects being created, updated, and deleted. Some object types may have additional events related to their lifecycle. Payment objects, for example, also have a 'paid' event which is triggered when a payment is made.
2. Entities
The following entities are currently set up to work with hooks in the vCita system along with the events that are available for each one.
- Clients - 'created', 'updated', 'deleted'
- Appointments - 'created', 'updated', 'deleted'
- Payments - 'created', 'paid', 'updated', 'deleted'
Directory Level webhooks:
- Account Promotional Muted - 'pivot/event'
- Account Marked as Spammer - 'pivot/event'
- Account Details Updated - 'pivot/update'
Subscribing to hooks
In order to subscribe to a hook you would need to make a call to the subscription route with proper authentication headers and specify:
- the entity type for which you want to receive updates
- the event you are interested in
- the target_url to which you want vCita to send updates (your server).
The entity and event type are sent in a single 'event' field by combining the entity and event type with a '/' character between them. If you want to be updated when a client is created the 'event' parameter should be passed as 'client/created'. The parameters should be sent as a JSON string in the body of the POST.
So, if you are interested in receiving a ping every time a new payment has been made, you would make the following call:
POST https://hook.vcita.com/v1/subscriptions/standard/subscribe
{"event":"client/create","target_url":"URL_TO_SEND_UPDATES"}
Note: The subscribe call needs to have the same authorization headers as every other call to the vCita API.
If the subscription was successful you will get the following response:
{
"response": "Subscribed"
}
If you wish to unsubscribe from receiving updates, you would make an unsubscribe call with the target_url set up to receive updates as follows:
POST https://hook.vcita.com/v1/subscriptions/standard/unsubscribe
{"target_url":"URL_TO_SEND_UPDATES"}
Note: The unsubscribe call needs to have the same authorization headers as every other call to the vCita API.
If the unsubscribe was successful you will get the following response:
{
"response": "Unsubscribed"
}