Subscribe to Webhook

post

https://api.vcita.biz/platform/v1/webhook/subscribe

Overview

Subscribe to webhook notifications. Webhooks allow you to receive real-time notifications when specific events occur in the system. You must specify the event (a combined string of entity and event_type in the format 'entity/event_type') and the target_url where notifications will be sent.

Available for Staff and Directory Tokens.

Event Format

The event parameter uses the format entity/event_type where:

entity: The object type to monitor (e.g., 'client', 'business', 'meeting', 'payment')
event_type: The action that triggers the notification (e.g., 'created', 'updated', 'deleted')

Common Events

client/created - New client created
business/created - New business created
meeting/created - New meeting scheduled
meeting/cancelled - Meeting cancelled
payment/paid - Payment received
invoice/issued - Invoice issued

Error Responses

Returns HTTP 500 with {"response": "Not Subscribed"} when subscription fails (e.g., invalid event format, service unavailable).

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

event

string

enum

required

The event to subscribe to in the format 'entity/event_type'. The entity is the object type to monitor (e.g., 'client', 'business', 'meeting') and event_type is the action that triggers the webhook (e.g., 'created', 'updated', 'deleted', 'cancelled').

event_type

uri

The type of event that triggers the webhook notification. This specifies what action or state change should trigger the webhook. Common event types include: 'create' (object created), 'update' (object updated), 'delete' (object deleted), 'scheduled' (appointment/event scheduled), 'cancelled' (appointment/event cancelled), 'rejected' (request rejected, e.g., business creation failure), 'paid' (payment received), 'recorded' (payment recorded), 'issued' (invoice/estimate issued), 'sent' (message sent), and 25 other event types. See the enum list below for all available event types.

Responses

201Webhook subscription created successfully. Returns a subscription_id that can be used to identify this subscription.

400Bad Request - Invalid parameters provided. The event format may be invalid (must be 'entity/event_type'), the target_url format is incorrect, or required fields are missing.

401Unauthorized - Invalid or missing authentication token.