Webhook Guide
This guide explains how to configure and use webhooks to receive real-time updates on application statuses from Carousel.
Creating a Workflow with Data Export
Carousel lets you collect and verify applicant data using a configurable, step-based workflows. You can customize, configure and white label each workflow, directly from the Portal, no code needed.
How to Set It Up
- Log in to the Carousel Portal
- Navigate to: Dashboard → Workflows → Create New Workflow
- Use the drag-and-drop builder to build your flow
- Add a Data Export step at the end
Configuring the Data Export Step
The Data Export step automatically sends collected applicant data to your system using a secure POST request.
Setup Instructions
- Set Export Destination to
Webhook - Enter your POST URL (the endpoint on your system)
- Click Confirm to save
Once the applicant reaches this step, Carousel will send the workflow data as structured JSON.
Webhook Events
Carousel will automatically send webhook events to your configured POST URL as the applicant progresses through the workflow.
There are three main events:
1. Application Created
Triggered when an applicant first creates an application (logs in with phone number).
Sample Payload
{
"loanApplicationId": "28b25f25-43b7-4871-ab47-239faaefbe10",
"phoneNumber": "+1 (605) 555-5555",
"apiUrl": "https://yourwebhook.com",
"createdAt": "2025-08-14T20:52:22.589Z",
"externalCustomerId":"your_customer_id",
"system": {
"step": "Loan Product",
"status": "Initializing",
"updatedAt": "2025-08-14T20:52:21.233Z"
},
"application": {
"status": "In Progress",
"updatedAt": "2025-08-14T20:52:21.233Z"
},
"updatedAt": "2025-08-14T20:52:22.589Z"
}2. Application Finished All Steps
Triggered when the applicant finishes all required steps.
{
"loanApplicationId": "20ca981e-b94d-426a-a74a-9e17f315c7fc",
"phoneNumber": "+1 (605) 555-5555",
"apiUrl": "https://yourwebhook.com",
"createdAt": "2025-08-14T20:52:22.589Z",
"externalCustomerId":"your_customer_id",
"system": {
"step": "Loan Product",
"status": "Initializing",
"updatedAt": "2025-08-14T20:52:21.233Z"
},
"application": {
"status": "Completed",
"updatedAt": "2025-08-14T20:52:21.233Z"
},
"dataStep": [
{
"step": "Loan Product",
"data": {
"id": "4361048b-5a52-46e6-ade6-a923ce39bb71",
"calculatorConfig": {
"upfrontFee": 0,
"originationFee": 0,
"brokerageFeePercent": 0
},
"calculatorType": 0,
"annualInterest": 5,
"minimumLoanAmount": 500,
"name": "cll",
"amount": 500,
"assignments": [],
"applicationDate": "2025-02-17T16:08:00.304Z",
"approvalDate": "2025-02-17T16:10:09.001Z",
"businessId": "e35cba52-a7f3-53c1-a47c-e539aa26d681",
"externalCustomerId": null,
"detailsOnUseOfFunds": null,
"purposes": ["Inventory"],
"urgencyOfFunds": null
}
},
{
"step": "Identity",
"data": {
"gender": "Male",
"dateOfIssue": "2024-10-10T00:00:00.000Z",
"fullName": "JOHN DOE",
"country": "CAN",
"dateOfBirth": "1998-03-08T00:00:00.000Z",
"dateOfExpiration": "2027-06-30T00:00:00.000Z",
"documentNumber": "H0653-00009-80308",
"province": "ON",
"frontImageUrl": "https://staging.api.oncarousel.com/uploads/kyc/330b8683-1428-4f94-a558-3c9c2db0dec4.jpeg?Expires=1767726190&Key-Pair-Id=K1G5A68240S8O&Signature=HWka0sGDCY96n0DsQaw37PEqghDXR4TkR0sESFEPL5Uw9iF3UTunI2KVLsVOgjg0PkSpr3dYLoBx9O4rBiJUE9XIqhpJk1b4CcPuETT1SMMyF89M82F1TPlx7gyBlBtF3N5eilvK1EnWJc8CPL4Q~-Z64CLOU6HMmFEg1KpZ2yauGH3OWwMXVXWFjOk2JLzZv1JRYFGqYVTWtxOswgZhFf8tiZPLHfHElHAI1E6huPQ9s5JCFO3LeOU2MjWkjz3Mr2yL7RtLKjjOrlW5HAEvXJ-BgOR7HBSL9XntY7VWxCBSxJZ3A~mex3t4tif7aZY079dWpOVmxYwTPZ9OgBmVDw__"
}
},
{
"step": "Bank Account",
"data": {
"loginId": "6433cf6a-0879-4ef0-5a2a-08d91642f9c6",
"bankAccount": [] // This step is still processing so no bank accounts were saved
}
},
{
"step": "Custom Questionnaire",
"data": {
"questions": [
{
"id": "5bbb1eb4-57c3-4c0c-aa08-b1a4a29eab85",
"name": "What is the full legal name of your company ?",
"answer": "Spheregbs"
},
{
"id": "5f3edc6e-6247-47f1-8a15-be6c271b8788",
"name": "Would you like for the lease to be under your company or personal ?",
"answer": "Company"
},
{
"id": "2de688e5-3ae1-46bb-b587-669f2168652d",
"name": "Address from where vehicle will operate?",
"answer": ""
}
]
}
}
],
"updatedAt": "2025-07-22T15:55:23.986Z"
}
3. Application Completed Processing All Data
Triggered when the applicant finishes the entire workflow and the data finishes processing. This includes all collected data.
Sample Payload
{
"loanApplicationId": "20ca981e-b94d-426a-a74a-9e17f315c7fc",
"phoneNumber": "+1 (605) 555-5555",
"apiUrl": "https://yourwebhook.com",
"createdAt": "2025-08-14T20:52:22.589Z",
"externalCustomerId":"your_customer_id",
"system": {
"step": "Loan Product",
"status": "Initializing",
"updatedAt": "2025-08-14T20:52:21.233Z"
},
"application": {
"status": "Completed",
"updatedAt": "2025-08-14T20:52:21.233Z"
},
"dataStep": [
{
"step": "Loan Product",
"data": {
"id": "4361048b-5a52-46e6-ade6-a923ce39bb71",
"calculatorConfig": {
"upfrontFee": 0,
"originationFee": 0,
"brokerageFeePercent": 0
},
"calculatorType": 0,
"annualInterest": 5,
"minimumLoanAmount": 500,
"name": "cll",
"amount": 500,
"assignments": [],
"applicationDate": "2025-02-17T16:08:00.304Z",
"approvalDate": "2025-02-17T16:10:09.001Z",
"businessId": "e35cba52-a7f3-53c1-a47c-e539aa26d681",
"externalCustomerId": null,
"detailsOnUseOfFunds": null,
"purposes": ["Inventory"],
"urgencyOfFunds": null
}
},
{
"step": "Identity",
"data": {
"gender": "Male",
"dateOfIssue": "2024-10-10T00:00:00.000Z",
"fullName": "JOHN DOE",
"country": "CAN",
"dateOfBirth": "1998-03-08T00:00:00.000Z",
"dateOfExpiration": "2027-06-30T00:00:00.000Z",
"documentNumber": "H0653-00009-80308",
"province": "ON",
"frontImageUrl": "base64jpeg"
}
},
{
"step": "Bank Account",
"data": {
"loginId": "6433cf6a-0879-4ef0-5a2a-08d91642f9c6",
"bankAccount": [
{
"accountTitle": "Investments",
"accountNumber": "INV00001",
"institutionNumber": "",
"institutionName": "FlinksCapital",
"transitNumber": "",
"category": "Products",
"type": "RRSP",
"currency": "CAD",
"balanceAvailable": 0,
"balanceCurrent": 100000,
"balanceLimit": 0,
"overdraftLimit": 0,
"holder": {
"fullname": "John Doe",
"email": "[email protected]",
"phoneNumber": "(514) 333-7777",
"address": {
"address": "1275 avenue des Canadiens-de-Montréal",
"city": "Montréal",
"province": "QC",
"zipCode": "H3B 5E8",
"country": "CA"
}
}
}
]
}
},
{
"step": "Custom Questionnaire",
"data": {
"questions": [
{
"id": "5bbb1eb4-57c3-4c0c-aa08-b1a4a29eab85",
"name": "What is the full legal name of your company ?",
"answer": "Spheregbs"
},
{
"id": "5f3edc6e-6247-47f1-8a15-be6c271b8788",
"name": "Would you like for the lease to be under your company or personal ?",
"answer": "Company"
},
{
"id": "2de688e5-3ae1-46bb-b587-669f2168652d",
"name": "Address from where vehicle will operate?",
"answer": ""
}
]
}
}
],
"updatedAt": "2025-07-22T15:55:23.986Z"
}
Important: Document & Image Handling (S3 Links)
Carousel no longer sends documents or images as base64 in webhook payloads.
Instead, file fields (for example frontImageUrl) contain a temporary, pre‑signed Amazon S3 URL.
How It Works
- The URL points to a file stored in Carousel’s Amazon S3 bucket
- The URL is publicly accessible but expires after 15 minutes
- After expiration, the link will no longer be valid
Required Action (Recommended)
When your system receives a webhook containing file URLs:
- Immediately download the file from the S3 URL
- Store it securely in your own system or storage provider
- Do not rely on the URL for long‑term access
⚠️ If the URL expires before you download the file, the document cannot be accessed using that link.
Webhook Failure & Retry
If your webhook endpoint is unavailable, times out, or fails to process the payload (for example due to expired file links), you can manually re‑trigger the webhook.
Retry from the Portal
- Log in to the Carousel Portal
- Open the relevant Application
- Navigate to the Webhook section
- Click Re‑send Webhook
This will send the latest available payload again, including fresh S3 URLs for any files.
Support
Need help with:
- Configuring workflows
- Webhook setup
- Payload troubleshooting
- POS launch methods
We're here to help: Speak to Support
Updated 2 days ago