Retreat Guru API

The Application Programming Interface (API) provides access to program registration and transaction information.

The API

To access the API documentation for your center, log on to your Retreat Guru software and navigate to Reg Settings > API. 

On this page, you'll find documentation for:

• Token - used to access your data via custom code.
• API documentation - specific for your site.
• API endpoint - for testing your API connection.

Alternatively, if the API is not enabled for your site, you may view our general API documentation (without a token or endpoint for testing).

See also, Create an Integration with Zapier.

Webhooks

Webhooks allow your website (integration via API) to listen for events in the Retreat Guru application. This allows your web developer to set up custom code that executes when a particular event happens.

If webhooks are not enabled for your site, contact your friendly support guru. 

For example: when a registration is updated you could set up custom code to send an email.

• Object Type: the object the action is happening to
  • Programs
  • Registrations
  • Transactions
• Action : the action happening to the object
  
  • Create
  • Update
  • Delete
• Target URL: the custom URL to receive webhook event requests
  
  • Your web developer will set up code to execute when a request is made to this URL.
    
    

Testing Webhooks

Once you've saved your webhooks, click "test" to send a test request. It will use the most recently created object in that object type.

You can set the default timeout to give the request more time to process. If your request is failing at a time of >5000ms, there is likely an error on your site.

Example webhook request data:

body { 

     timestamp: "2022-10-21T16:30:33Z",
     object_id: "32",
     object_type: "registrations",
     action: "create",
     url: "http://dev.programs.test/api/v1/registrations/32" 
}

• Timestamp: time that the action happened.
• URL: a link to the API endpoint to fetch the full data set for the object. (see API details above).
  
  

Exploring Webhooks

If you want to explore webhooks in real-time, we suggest using a service like Pipedream’s Request Bin or ngrok.

An example setup in Request Bin would look like this:

1. Sign up to Request Bin.

2. Create a new Request Bin, or click "New Source".

3. Choose the “HTTP / Webhook” option.

4. Next, choose “HTTP Requests" (Get a unique URL where you can send requests to trigger your work.)

5. Use the defaults on the next screen and click Save.

6. Click Deploy.

7. Copy the URL provided.

8. In Retreat Guru, navigate to Settings > API tab.

9. Add a new webhook for any entity type and action (ex: Registration, Update).

10. Add the URL that was provided by Request Bin.

11. Save.

If you added a webhook for Registration Update, for example, you can edit a registration in Retreat Guru, and it will appear as a POST request in Request Bin under the logging window.

Testing Locally

The traditional approach of testing webhooks locally is through a proxy service like  ngrok. View general instructions for ngrok.

This works by installing ngrok locally, which would then act as a proxy between your local application and the outside world. The typical approach:

1. Build your app locally that accepts webhooks.
2. Sign up and install ngrok.
3. Initiate the ngrok command to your application.
4. Provide the unique ngrok URL that is outputted to the SaaS API tab / webhooks section.