The event object
The table below lists all events you can subscribe to.
When creating a subscription, include the event type codes in your request JSON (API) or select the events via your admin dashboard account (no-code).
| Family | Event Type codes (event resource.event trigger type) | Purpose |
|---|---|---|
| Embedded Capital / Embedded Insights | authorisation.enabled | Indicates a state when a merchant successfully authorises access of his/her PSP account to Groov via the Connect consent flow. |
| Embedded Capital / Embedded Insights | authorisation.failed | Indicates a state when a merchant does not authorise access of his/her PSP account to Groov via the Connect consent flow. As an institution, you will need to check with the merchant directly on reasons for not proceeding. |
| Embedded Capital / Embedded Insights | authorisation.revoked | Indicates a state when a merchant removes access to his/her PSP/commerce account having previously providing authorisation to the same. This could be merchant revoking directly via PSP account platform or requesting for data access removal via a provider like yourselves. |
| Embedded Capital / Embedded Insights | authorisation.connection_lost | Indicates a state when Groov has temporarily lost access to the partner/PSP/commerce provider. Groov will act swiftly to restore access back ASAP. Whilst in this state any new connections via the Connect flow will be unsuccessful. |
| Embedded Capital / Embedded Insights | authorisation.otp_required | Only relevant to institutions who use Groov's Connect API. Indicates a state when a merchant is required to provide OTP to Groov to get successfully authorised to access the merchant's PSP/commerce partner account. |
| Embedded Capital / Embedded Insights | ledger_alldata.primary_sync.complete | Indicates a state when Groov has completed data processing successfully for an authorised connected account. This will be the trigger for an institution to access Groov's unified API to retrieve ledgerAccount details/insights. |
| Embedded Capital / Embedded Insights | ledger_alldata.primary_sync.failed | Indicates a state when Groov has encountered an error whilst processing data for an authorised connected account. Whilst in this state, any call to Groov's API will return an error. The institution is advised to wait for the primary_sync.complete event before calling Groov's Unified data/insights API. |
| Embedded Capital | lead.created | Indicates a state when a lead has shown interest for Business Funding. |
| Embedded Capital | account.qualified | Indicates a state when a lead has converted to a fully qualified account and submitted all details for the Funding qualification step. |
| Embedded Capital | lead.not_qualified | Indicates a state when a lead has not converted to a fully qualified account and cannot be served. |
| Embedded Capital | deal_flow.created | Initiates a new deal flow / workflow for the account. |
| Embedded Capital | deal_flow.banking_info_available | A business account has either connected via Open Banking or has made banking information available. |
| Embedded Capital | deal_flow.business_details_updated | A business account has updated its KYC/KYB info. |
| Embedded Capital | deal_flow.qualification_in_progress | The funding request from the business account is in qualification/quotation cycle. |
| Embedded Capital | deal_flow.onboarding_in_progress | The funding request has an offer accepted and onboarding with a lender is in progress. |
| Embedded Capital | deal_flow.won | The funding request was approved, account funded and deal is now won. |
| Embedded Capital | deal_flow.closed | The funding request was declined or cancelled or offers expired, account couldn't be funded, the deal flow stands closed. |
| Embedded Capital | capital_application.submitted | MCA application has been submitted with a qualified lender. |
| Embedded Capital | capital_application.offer_available | MCA application has received 1 or more offers from a lender. |
| Embedded Capital | capital_application.offer_submitted | MCA application has a confirmed offer accepted and submitted for processing. |
| Embedded Capital | capital_application.action_required | MCA application has pending actions (e.g. additional documents) to progress. |
| Embedded Capital | capital_application.contract_signed | Business customer has signed the funding application contract. |
| Embedded Capital | capital_application.approved | MCA application has been approved by the lender. |
| Embedded Capital | capital_application.declined | MCA application has been declined by the lender. |
| Embedded Capital | capital_application.cancelled | MCA application has been cancelled by the lender or the business customer didn't wish to proceed. |
| Embedded Capital | capital_account.funded | MCA advance has been funded to the customer's bank account. |
| Embedded Capital | capital_account.active | MCA account has been set up successfully and is active/funding available. |
| Embedded Capital | capital_account.closed | MCA account repaid and/or has been closed. |
| Embedded Capital | email_verification.complete | OTP verification has been successful for your customer. |
| Embedded Capital | email_verification.failed | OTP verification has failed for your customer. |
| Embedded Capital | business_loan_application.submitted | Business Loan application has been submitted with a qualified lender. |
| Embedded Capital | business_loan_application.offer_available | Business Loan application has received 1 or more offers from a lender. |
| Embedded Capital | business_loan_application.offer_submitted | Business Loan application has a confirmed offer accepted and submitted for processing. |
| Embedded Capital | business_loan_application.action_required | Business Loan application has pending actions (e.g. additional documents) to progress. |
| Embedded Capital | business_loan_application.contract_signed | Business customer has signed the funding application contract. |
| Embedded Capital | business_loan_application.approved | Business Loan application has been approved by the lender. |
| Embedded Capital | business_loan_application.declined | Business Loan application has been declined by the lender. |
| Embedded Capital | business_loan_application.cancelled | Business Loan application has been cancelled by the lender or the business customer didn't wish to proceed. |
| Embedded Capital | business_loan_account.funded | The customer has withdrawn the funds. |
| Embedded Capital | business_loan_account.active | Business Loan account has been set up successfully and is active/funding available. |
| Embedded Capital | business_loan_account.closed | Business Loan account repaid and/or has been closed. |
Receive Groov events in your webhook endpoint
Listen for events from Groov on your webhook endpoint so your integration/your app can automatically trigger reactions/CTAs.
Create an event destination to receive events at an HTTPS webhook endpoint. After you register a webhook endpoint, Groov can push real-time event data to your application’s webhook endpoint when events happen in your Groov account. Groov uses HTTPS to send webhook events to your app as a JSON payload that includes an Event related object.
Receiving webhook events helps you respond to asynchronous events, such as when a customer gets funded for MCA, a customer gets offers or any of the supported event types as per the list above
Get started
To start receiving webhook events in your app:
- Create a webhook endpoint handler to receive event data POST requests.
- Test your webhook endpoint handler locally or in a sandbox mode.
- Create a new event destination (using the admin dashboard console or using the webhook endpoints) to register your webhook endpoint’s accessible URL so Groov knows where to deliver events. Registered webhook endpoints must be publicly accessible HTTPS URLs.
- Secure your webhook endpoint - Secure your integration by making sure your handler verifies that all webhook requests are generated by Groov.
You can register and create one endpoint to handle several different event types at the same time, or set up individual endpoints for specific events.
The webhook secret key (Base64 encoded) is shared with you the first time when you register a new webhook URL OR you can call the GET webhook endpoint to retrieve the details later.
Groov-Signature Know-How
Groov generates signatures using a hash-based message authentication code (HMAC) with SHA-256. The X-Groov-Webhook-Signature is included in each signed event. To prevent downgrade attacks, refer to Note below.
Here's a step-by-step guide on how to process/verify the X-Groov-Webhook-Signature block:
- Extract the base64 encoded signature from the X-Groov-Webhook-Signature header.
- Retrieved signature is Base64 encode, so you will need to decode it first.
- Compute the expected signature with the SHA-256 function. Use the webhook secret key (which is also Base64 encoded) and the request payload string as the message.
- Compare the generated hash signature with the decoded one extracted from the header.
Note: To protect against timing attacks, use a constant-time-string comparison to compare the expected signature to each of the received signatures.
Receive Groov events via Notifications
Groov currently supports in-app notifications and email based notifications
Create a Notification subscription using your admin account dashboard to
- receive events at your configured email accounts (tab: Platform Notifications)
- to send email notifications to your customer (Tab: Customer Notifications).
After you register and configure an email notification entry, Groov can push real-time event data to the destination email accounts when events happen in your Groov account. Groov uses a standard template to notify you of all Platform Notifications but allows you to define bespoke/custom templates for your customer notifications.
Receiving email based notification events helps you as well as your customer respond to journey lifecycle events, such as when a customer gets funded for MCA, a customer gets offers or any of the supported event types as per the list above.
Platform Notifications
You can register and create one email notification and add multiple email accounts to recieve several different event types at the same time, or set up individual email notifications for specific events or email notifications per email account to customise who gets what notifcation.
Customer Notifications
You can register and create email notifications per event resource so all your customers recieve the configured event type codes using the event resource template