Webhooks

Listen for events on your Groov account so your integration can automatically trigger reactions.

Get real-time notifications

Webhooks are "user-defined HTTP callbacks". Groov uses webhooks to notify your application when an event happens regarding your connected ledger account. In our setup, Webhooks should be used to understand asynchronous events such as when a ledger account authorises their account connection to you via Groov, data aggregation is complete, insights are available, in-life data for an ongoing connected account changes/gets added.

How Groov uses webhooks

A webhook enables Groov to push real-time notifications to your app. Groov uses HTTPS to send these notifications to your app as a JSON payload. 

Steps to setup webhooks

Please follow the steps below to setup your webhook URLs:

1. Create a webhook endpoint as an HTTP endpoint (URL) on your local server.

2. Handle requests from Groov by parsing each event object, return 2xx response status codes.

3. Test that your webhook endpoint is working properly using the Groov test toggle/sandbox account

4. Deploy your webhook endpoint so it’s a publicly accessible HTTPS URL.

5. Register your publicly accessible HTTPS URL in the Groov dashboard.

Register your webhook URL on Groov

via dashboard setup

Please follow the steps below to register your webhook URL(s) on Groov dashboard:

1. Login to your developer account on Groov Portal

2. As an admin role or a developer role, you will have access to the Developers section as per the visual.

3. Access the Developers menu option and navigate to Web hooks section (Note:you can create separate webhook endpoints for test/sandbox setup vs your Live setup, use the toggle switch to setup accordingly)

4. Add an endpoint, it will ask for the URL details, description (provide a brief note of what this endpoint does in your app), select the Groov events you want to subscribe to and click on Create endpoint. Two key events for the initial setup will be:

   1. authorisation.enabled  → This event type allows you to receive notifications as soon as your customer provides authorisation to their merchant/commerce/trading partner account (like to their Stripe or SumUp or Worldpay account for example)
   2. ledger_alldata.primary_sync.complete   → This event type allows you to receive notification on when to call the Groov unified APIs to retrieve the unified data about your customer/ledger account. Once a partner connection gets authorised, Groov will source the scoped data/information, transform and unify it. As soon as the data is available via Groov's API for the connected ledger account, Groov will send notifications for this event type
5. Thats it, you are all set

via Groov API 

You can also setup webhook URL on your Groov account by tapping on Groov's API as follows:

1. Access the following endpoint to perform a POST operation
   1. https://app.wearegroov.io/api/swagger-ui/index.html?configUrl=/api/v3/api-docs/swagger-config#/Webhook%20endpoints/save
2. Provide the URL details, description (provide a brief note of what this endpoint does in your app), select the Groov events you want to subscribe to and do a POST call via the above REST API endpoint . Two key events for the initial setup will be:
   1. authorisation.enabled  → This event type allows you to receive notifications as soon as your customer provides authorisation to their merchant/commerce/trading partner account (like to their Stripe or SumUp or Worldpay account for example)
   2. ledger_alldata.primary_sync.complete   → This event type allows you to receive notification on when to call the Groov unified APIs to retrieve the unified data about your customer/ledger account. Once a partner connection gets authorised, Groov will source the scoped data/information, transform and unify it. As soon as the data is available via Groov's API for the connected ledger account, Groov will send notifications for this event type
3. Thats it, you are all set

Manage your Webhook setup ongoing

via dashboard setup

On your Groov dashboard account, navigate to Developers → Webhooks section,

1. To update an existing endpoint: select the webhook endpoint you want to amend/update, click on EDIT icon to make changes. Save the changes 
2. To delete an existing webhook endpoint: select the webhook endpoint you want to delete and click on the Delete icon

via Groov API

You can also manage webhook URL on your Groov account by tapping on Groov's API as follows:

1. To update an existing endpoint: https://app.wearegroov.io/api/swagger-ui/index.html?configUrl=/api/v3/api-docs/swagger-config#/Webhook%20endpoints/edit 
2. To delete an existing webhook endpoint: https://app.wearegroov.io/api/swagger-ui/index.html?configUrl=/api/v3/api-docs/swagger-config#/Webhook%20endpoints/delete
3. To query an existing endpoint: https://app.wearegroov.io/api/swagger-ui/index.html?configUrl=/api/v3/api-docs/swagger-config#/Webhook%20endpoints/get
4. To query all your webhook endpoints (if you have more than 1: https://app.wearegroov.io/api/swagger-ui/index.html?configUrl=/api/v3/api-docs/swagger-config#/Webhook%20endpoints/getAllWebhooks