Webhooks

What is Webhook?

Webhooks are an incredibly useful and resource-light way to implement event reactions. Webhooks provide a mechanism whereby a server-side application can notify a client-side application when a new event (that the client-side application might be interested in) has occurred on the server.

Webhooks are also sometimes referred to as “Reverse APIs”. In APIs, the client-side application calls (consumes) the server-side application. Whereas, in the case of webhooks it is the server-side that calls (consumes) the webhook (the end-point URL provided by the client-side application), i.e. it is the server-side application that calls the client-side application.

Webhooks operate on the concept of “event reaction” (don’t call me, I’ll call you if I have something new), and thus avoids the need for constant polling of the server-side application by the client-side application. Thus, rather than the client-side application constantly polling the server-side application to check for new events, the server-side application calls the client-side application (by invoking a client provided webhook URL) anytime the server-side has something new to report to the client.

Webhooks and SynthesisVR

The webhooks support is the only allowed way to receive events from Synthesis “as they happen”.
The Webhook configuration can be found under:

• Administration >> Advanced Settings –> the “Online & Email Settings” dropdown >> Web Widgets & API –> the “API & Webhooks” tab.

All events are HTTP POSTed to the related webhook URL. The URL must start either with http:// or https:// (preferred).

Your webhook handler has to respond within 2 seconds and the response is ignored by Synthesis. Synthesis won’t attempt resending the webhook if your webhook endpoint isn’t reachable.

All webhook events consist of JSON data.
One HTTP POST message may contain an array of multiple webhooks.
 

JSON SCHEMES:

SESSION WEBHOOK

• uuid — the Synthesis session id. It can be used for obtaining more information through the sessions API (https://synthesisvr.com/knowledge-base/reading-session-data-through-api/ — use the uuid: search option)
• action — possible values:
  • create – upon creation of the session
  • delete – upon removal of the session
• location — contains your location title. If you need to distinguish between multiple locations, you better configure unique webhook URLs rather than rely on the location title. It is included just your webhook reading experience more pleasant 🙂
• stations — provides the number of stations in session
• customerid — the ID of your customer. The full customer profile can be fetched through the customers API (https://synthesisvr.com/knowledge-base/reading-customers-data-through-api/ — use the id value as a search parameter)

 
Examples:

• [{“uuid”: “41509791-3de8-5bb9-b4fc-a9753da95aad”, “action”: “create”, “location”: “Kamen Test”, “stations”: 1, “customerid”: 7685}]
• [{“uuid”: “41509791-3de8-5bb9-b4fc-a9753da95aad”, “action”: “delete”, “location”: “Kamen Test”, “stations”: 1, “customerid”: 7685}]

More webhook options will come as the need of them emerge. If you have any specific request. please let us know: [email protected]