INTRODUCTION TO WEBHOOK INTEGRATION

This documentation explains how to integrate your application with our system using webhooks. We will send payloads via webhook for different events when they occur in our system.

Overview: Our webhook system allows real-time communication between applications. When specific events occur in our system, we automatically send HTTP POST requests with JSON payloads to your configured webhook endpoint.

INTEGRATION CREDENTIALS

To integrate with our system, you need to configure the following credentials. These credentials are essential for secure communication between Insure Connect Academy and your external systems.

Overview: Every webhook payload transmitted from IC Academy will contain the IC ORG ID, ensuring proper identification and routing. All integration credentials are automatically generated by our system and should be refreshed periodically for enhanced security.

Field	Type	Description	Required	Example
IC ORG ID	String	Your organization's unique identifier in the IC Academy system. Every organization is assigned a unique ORG ID that must be kept on the receiver side for future webhook communications. This ID is included in every payload for proper identification.	Yes	`IC1P76I43OB`
Client ID	String	A unique identifier used for webhook payload transmissions. This ID is automatically generated by IC Academy and is essential for authenticating webhook requests to your system.	Yes	`IC_C1L2I3E4N5T6I7D_1756296227`
Client Secret	String	The most important and secured credential in the integration. IC Academy uses the client secret for encryption purposes to ensure payload security. NEVER expose this secret publicly as it compromises the security of your webhook communications.	Yes	`C1L2I3E4N5T6S7E8C9R10E11T_1756296227`
Webhook URL	URL	The endpoint URL specified by you where IC Academy will send all webhook payloads. This URL must be accurate and accessible at all times to ensure reliable webhook delivery. All communications will be directed to this endpoint only.	Yes	`https://yourdomain.com/webhook/endpoint`

🔒 Security Notes

All integration credentials (IC ORG ID, Client ID, and Client Secret) are automatically generated by IC Academy
Credentials should be refreshed periodically for better security - this can be done in the organization settings
The Client Secret is used for encryption and must never be exposed or shared publicly
Ensure your webhook URL endpoint is always accessible and can handle incoming POST requests
Store credentials securely in your system and use environment variables for production deployments

🛡️ Webhook Security Headers (Recommended)

IC Academy sends additional security headers with each webhook payload to help verify the authenticity and integrity of the request.

Header	Description	Example
`X-IC-Signature`	A cryptographic signature generated by combining the payload body and timestamp, then encrypting this combination using your Client Secret with HMAC-SHA256. On the receiver end, you should perform the same encryption process and compare the resulting signature to verify authenticity.	`sha256=abc123def456...`
`X-IC-Timestamp`	Unix timestamp indicating when the webhook was sent. This helps prevent replay attacks by allowing you to reject requests that are too old (recommended: reject requests older than 5 minutes).	`1640995200`

📝 Note: While signature and timestamp verification is a recommended security best practice, it is not mandatory for basic webhook functionality. However, implementing these security measures significantly enhances the security of your webhook integration.

🔍 Signature Verification Process

To verify the authenticity of incoming webhooks, follow these steps:

Extract the X-IC-Signature and X-IC-Timestamp headers from the incoming webhook request
Combine the raw payload body with the timestamp value (payload + timestamp)
Create an HMAC-SHA256 hash of this combined string using your Client Secret as the key
Compare the generated signature with the X-IC-Signature header value
If the signatures match, the webhook is authentic and has not been tampered with
Additionally, check that the timestamp is recent (within 5 minutes) to prevent replay attacks

💻 Implementation Example:

// Pseudo-code example
received_signature = request.headers["X-IC-Signature"]
received_timestamp = request.headers["X-IC-Timestamp"]
payload_body = request.body

// Create expected signature
combined_data = payload_body + received_timestamp
expected_signature = HMAC_SHA256(combined_data, client_secret)

// Verify signature
if (expected_signature == received_signature) {
    // Webhook is authentic
    process_webhook(payload_body)
} else {
    // Reject webhook - potential security issue
    return 401 Unauthorized
}

💡 Best Practices

Keep the IC ORG ID on your receiver side for all future webhook communications
Implement proper webhook signature verification using the Client Secret
Set up monitoring and logging for your webhook endpoint to track delivery status
Use HTTPS endpoints only for secure webhook communications

WEBHOOK EVENTS

Our system supports the following webhook events. Each event has a unique payload structure:

USER CREATED

This webhook is triggered immediately when a new user account is successfully created in the Insure Connect Academy system. The event fires after user registration is complete and includes all essential user information along with their organization details. This is typically the first webhook you'll receive for a new user, making it perfect for setting up user profiles in your external systems.

Sample Payload:

{
    "event": {
        "type": "user.created",
        "id": "evt_65a1b2c3d4e5f6",
        "timestamp": "2025-01-15T10:30:45.123Z",
        "data": {
            "user": {
                "ic_user_id": "IC_U1S2E3R4I5D6_1756296227",
                "email": "john.doe@example.com",
                "first_name": "John",
                "last_name": "Doe"
            },
            "organization": {
                "ic_org_id": "IC_O1R2G3I4D5_1756296227"
            }
        }
    },
    "metadata": {
        "version": "1.0",
        "source": "insure_connect_academy",
        "event_type": "user_created"
    }
}

Field Descriptions:

Field	Type	Description	Required
`event.type`	String	The type of webhook event	Yes
`event.id`	String	Unique identifier for this webhook event	Yes
`event.timestamp`	String (ISO 8601)	Timestamp when the event occurred	Yes
`event.data.user.ic_user_id`	String	Unique user identifier in the system	Yes
`event.data.user.email`	String	User's email address	Yes
`event.data.user.first_name`	String	User's first name	Yes
`event.data.user.last_name`	String	User's last name	Yes
`event.data.organization.ic_org_id`	String	Unique organization identifier	Yes
`metadata.version`	String	API version number	Yes
`metadata.source`	String	Source system identifier	Yes
`metadata.event_type`	String	Snake case version of event type	Yes

USER ENROLLED

This webhook is triggered when a user successfully enrolls in any content (module) or curriculum within the academy. The event fires immediately after enrollment is processed and includes detailed information about what the user enrolled in, whether it's a standalone module or part of a larger curriculum. This webhook is essential for tracking user learning paths and managing access to content in your external systems.

Sample 1: User Enrolled in Curriculum

This sample shows the payload structure when a user enrolls in a curriculum program. Note that curriculum enrollments include a curriculum_modules array listing all modules within the curriculum.

{
    "event": {
        "type": "user.enrolled",
        "id": "evt_65a1b2c3d4e5f7",
        "timestamp": "2025-01-15T11:00:45.123Z",
        "data": {
            "user": {
                "ic_user_id": "IC_U1S2E3R4I5D6_1756296227",
                "email": "john.doe@example.com",
                "first_name": "John",
                "last_name": "Doe"
            },
            "organization": {
                "ic_org_id": "IC_O1R2G3I4D5_1756296227"
            },
            "enrollment": {
                "item_type": "curriculum",
                "status": "enrolled",
                "enrolled_at": "2025-01-15T11:00:45.123Z",
                "item_title": "Complete Insurance Professional Program",
                "item_description": "Comprehensive training program covering all aspects of insurance",
                "ic_content_id": null,
                "ic_curriculum_id": "IC_C1U2R3R4I5C6U7L8U9M_1756296227",
                "curriculum_modules": [
                    {
                        "module": {
                            "title": "Insurance Fundamentals",
                            "short_description": "Learn the basics of insurance principles",
                            "thumbnail_url": "https:\/\/example.com\/thumbnails\/module1.jpg",
                            "duration": "120",
                            "ic_content_id": "IC_C1O2N3T4E5N6T_1756296227"
                        }
                    },
                    {
                        "module": {
                            "title": "Risk Management",
                            "short_description": "Understanding risk assessment and mitigation",
                            "thumbnail_url": "https:\/\/example.com\/thumbnails\/module2.jpg",
                            "duration": "90",
                            "ic_content_id": "IC_C1O2N3T4E5N6T_1756296228"
                        }
                    },
                    {
                        "module": {
                            "title": "Policy Administration",
                            "short_description": "Managing insurance policies effectively",
                            "thumbnail_url": "https:\/\/example.com\/thumbnails\/module3.jpg",
                            "duration": "150",
                            "ic_content_id": "IC_C1O2N3T4E5N6T_1756296229"
                        }
                    }
                ]
            }
        }
    },
    "metadata": {
        "version": "1.0",
        "source": "insure_connect_academy",
        "event_type": "user_enrolled"
    }
}

Sample 2: User Enrolled in Content (Standalone Module)

This sample shows the payload structure when a user enrolls in a standalone content/module that is NOT associated with any curriculum.

{
    "event": {
        "type": "user.enrolled",
        "id": "evt_65a1b2c3d4e5f8",
        "timestamp": "2025-01-15T11:30:45.123Z",
        "data": {
            "user": {
                "ic_user_id": "IC_U1S2E3R4I5D6_1756296227",
                "email": "john.doe@example.com",
                "first_name": "John",
                "last_name": "Doe"
            },
            "organization": {
                "ic_org_id": "IC_O1R2G3I4D5_1756296227"
            },
            "enrollment": {
                "item_type": "content",
                "status": "enrolled",
                "enrolled_at": "2025-01-15T11:30:45.123Z",
                "item_title": "Insurance Fundamentals Module",
                "item_description": "Learn the basics of insurance principles and practices",
                "ic_content_id": "IC_C1O2N3T4E5N6T_1756296227",
                "ic_curriculum_id": null
            }
        }
    },
    "metadata": {
        "version": "1.0",
        "source": "insure_connect_academy",
        "event_type": "user_enrolled"
    }
}

Sample 3: User Enrolled in Content (Part of a Curriculum)

This sample shows the payload structure when a user enrolls in a content/module that IS associated with a curriculum. Even though the user enrolled directly in the content, the ic_curriculum_id is included to show the relationship.

{
    "event": {
        "type": "user.enrolled",
        "id": "evt_65a1b2c3d4e5f9",
        "timestamp": "2025-01-15T12:00:45.123Z",
        "data": {
            "user": {
                "ic_user_id": "IC_U1S2E3R4I5D6_1756296227",
                "email": "john.doe@example.com",
                "first_name": "John",
                "last_name": "Doe"
            },
            "organization": {
                "ic_org_id": "IC_O1R2G3I4D5_1756296227"
            },
            "enrollment": {
                "item_type": "content",
                "status": "enrolled",
                "enrolled_at": "2025-01-15T12:00:45.123Z",
                "item_title": "Risk Management",
                "item_description": "Understanding risk assessment and mitigation strategies",
                "ic_content_id": "IC_C1O2N3T4E5N6T_1756296228",
                "ic_curriculum_id": "IC_C1U2R3R4I5C6U7L8U9M_1756296227"
            }
        }
    },
    "metadata": {
        "version": "1.0",
        "source": "insure_connect_academy",
        "event_type": "user_enrolled"
    }
}

Field Descriptions:

Field	Type	Description	Required
`event.type`	String	The type of webhook event	Yes
`event.id`	String	Unique identifier for this webhook event	Yes
`event.timestamp`	String (ISO 8601)	Timestamp when the event occurred	Yes
`event.data.user.ic_user_id`	String	Unique user identifier in the system	Yes
`event.data.user.email`	String	User's email address	Yes
`event.data.user.first_name`	String	User's first name	Yes
`event.data.user.last_name`	String	User's last name	Yes
`event.data.organization.ic_org_id`	String	Unique organization identifier	Yes
`event.data.enrollment.item_type`	String	Type of item enrolled in (content or curriculum)	Yes
`event.data.enrollment.status`	String	Enrollment status (enrolled)	Yes
`event.data.enrollment.enrolled_at`	String (ISO 8601)	Timestamp when enrollment occurred	Yes
`event.data.enrollment.item_title`	String	Title of the enrolled item	Yes
`event.data.enrollment.item_description`	String	Description of the enrolled item	No
`event.data.enrollment.ic_content_id`	String	Unique content/module identifier. Present when item_type is "content". Set to null when item_type is "curriculum"	Conditional
`event.data.enrollment.ic_curriculum_id`	String	Unique curriculum identifier. Always present when item_type is "curriculum". May also be present when item_type is "content" if that content is associated with a curriculum	Conditional
`event.data.enrollment.curriculum_modules`	Array	Array of modules included in the curriculum. Only present when item_type is "curriculum". Each module contains title, short_description, thumbnail_url, duration, and ic_content_id	Conditional

MODULE COMPLETED

This webhook is triggered when a user successfully completes a specific module or content piece. The event fires after the user has finished all requirements for the module and their completion status has been updated in the system. This webhook is crucial for tracking learning progress, updating user achievements, and potentially triggering curriculum completion checks if this was the final module in a curriculum.

Sample Payload:

{
    "event": {
        "type": "module.completed",
        "id": "evt_65a1b2c3d4e5f8",
        "timestamp": "2025-01-16T14:30:45.123Z",
        "data": {
            "user": {
                "ic_user_id": "IC_U1S2E3R4I5D6_1756296227",
                "email": "john.doe@example.com",
                "first_name": "John",
                "last_name": "Doe"
            },
            "organization": {
                "ic_org_id": "IC_O1R2G3I4D5_1756296227"
            },
            "enrollment": {
                "ic_content_id": "IC_C1O2N3T4E5N6T_1756296227",
                "module_title": "Insurance Fundamentals Module",
                "module_description": "Learn the basics of insurance principles and practices",
                "status": "completed",
                "enrolled_at": "2025-01-15T11:00:45.123Z"
            }
        }
    },
    "metadata": {
        "version": "1.0",
        "source": "insure_connect_academy",
        "event_type": "module_completed"
    }
}

Field Descriptions:

Field	Type	Description	Required
`event.type`	String	The type of webhook event	Yes
`event.id`	String	Unique identifier for this webhook event	Yes
`event.timestamp`	String (ISO 8601)	Timestamp when the event occurred	Yes
`event.data.user.ic_user_id`	String	Unique user identifier in the system	Yes
`event.data.user.email`	String	User's email address	Yes
`event.data.user.first_name`	String	User's first name	Yes
`event.data.user.last_name`	String	User's last name	Yes
`event.data.organization.ic_org_id`	String	Unique organization identifier	Yes
`event.data.enrollment.ic_content_id`	String	Unique content/module identifier	Yes
`event.data.enrollment.module_title`	String	Title of the completed module	Yes
`event.data.enrollment.module_description`	String	Description of the completed module	No
`event.data.enrollment.status`	String	Enrollment status (completed)	Yes
`event.data.enrollment.enrolled_at`	String (ISO 8601)	Original enrollment timestamp	Yes

CURRICULUM COMPLETED

This webhook is triggered when a user successfully completes an entire curriculum program. The event fires after all modules within the curriculum have been completed and the curriculum completion status has been updated. This represents a major learning milestone and is perfect for issuing certificates, updating user profiles with new qualifications, or triggering follow-up actions in your external systems.

Sample Payload:

{
    "event": {
        "type": "curriculum.completed",
        "id": "evt_65a1b2c3d4e5f9",
        "timestamp": "2025-01-20T16:45:45.123Z",
        "data": {
            "user": {
                "ic_user_id": "IC_U1S2E3R4I5D6_1756296227",
                "email": "john.doe@example.com",
                "first_name": "John",
                "last_name": "Doe"
            },
            "organization": {
                "ic_org_id": "IC_O1R2G3I4D5_1756296227"
            },
            "enrollment": {
                "ic_curriculum_id": "IC_C1U2R3R4I5C6U7L8U9M_1756296227",
                "curriculum_title": "Complete Insurance Professional Program",
                "curriculum_description": "Comprehensive training program covering all aspects of insurance",
                "status": "completed",
                "enrolled_at": "2025-01-15T10:00:45.123Z"
            }
        }
    },
    "metadata": {
        "version": "1.0",
        "source": "insure_connect_academy",
        "event_type": "curriculum_completed"
    }
}

Field Descriptions:

Field	Type	Description	Required
`event.type`	String	The type of webhook event	Yes
`event.id`	String	Unique identifier for this webhook event	Yes
`event.timestamp`	String (ISO 8601)	Timestamp when the event occurred	Yes
`event.data.user.ic_user_id`	String	Unique user identifier in the system	Yes
`event.data.user.email`	String	User's email address	Yes
`event.data.user.first_name`	String	User's first name	Yes
`event.data.user.last_name`	String	User's last name	Yes
`event.data.organization.ic_org_id`	String	Unique organization identifier	Yes
`event.data.enrollment.ic_curriculum_id`	String	Unique curriculum identifier	Yes
`event.data.enrollment.curriculum_title`	String	Title of the completed curriculum	Yes
`event.data.enrollment.curriculum_description`	String	Description of the completed curriculum	No
`event.data.enrollment.status`	String	Enrollment status (completed)	Yes
`event.data.enrollment.enrolled_at`	String (ISO 8601)	Original enrollment timestamp	Yes

INTEGRATION SETUP STEPS

Follow these step-by-step instructions to configure webhook integration with Insure Connect Academy. This guide will walk you through the complete setup process from login to testing.

Organization Admin Login

Log in to the Insure Connect Academy platform using your organization administrator credentials. Ensure you have the necessary permissions to access integration settings.

Navigate to the login page and enter your admin credentials. If you don't have admin access, contact your system administrator to grant you the required permissions.

Access Organization Settings

Once logged in, navigate to the organization settings section from the main dashboard or admin panel.

Look for the "Settings" or "Organization" menu item in the navigation. This is typically located in the top navigation bar or sidebar menu.

Navigate to Integration Tab

Within the organization settings, locate and click on the "Integration" tab to access webhook configuration options.

The Integration tab contains all the necessary settings for configuring webhook endpoints and managing integration credentials.

Copy Integration Credentials

Copy the IC ORG ID, Client ID, and Client Secret from the integration settings. These credentials will be used in your receiving application.

Important: Store these credentials securely in your application. The Client Secret is particularly sensitive and should never be exposed publicly. Use environment variables for production deployments.

Credentials to Copy:

IC ORG ID: Your organization's unique identifier
Client ID: Used for webhook payload transmissions
Client Secret: Used for encryption and signature verification

Configure Webhook URL

Paste your webhook endpoint URL in the designated field and click "Update Integration Settings" to save the configuration.

Ensure your webhook URL is accessible via HTTPS and can handle POST requests. The endpoint should be ready to receive and process webhook payloads.

URL Requirements:

Must use HTTPS protocol for security
Should be accessible 24/7 for reliable delivery
Must accept POST requests with JSON payloads
Should return appropriate HTTP status codes

Select Event Types

Choose which webhook event types you want to receive. You can select from user.created, user.enrolled, module.completed, and curriculum.completed events.

Select only the events that are relevant to your integration needs. You can always modify these selections later if your requirements change.

Available Event Types:

user.created - Triggered when a new user is created
user.enrolled - Triggered when a user enrolls in content
module.completed - Triggered when a user completes a module
curriculum.completed - Triggered when a user completes a curriculum

Save Configuration

Click "Update Integration Settings" to save your webhook configuration. Your integration is now ready to receive webhook events.

After saving, the system will start sending webhook events to your configured endpoint for the selected event types.

Refresh Credentials (Optional)

For enhanced security, you can refresh your Client ID and Client Secret by clicking the "Refresh Credentials" button in the top right corner of the integration settings.

After clicking refresh, new credentials will be generated. Make sure to update your receiving application with the new credentials and click "Update Integration Settings" to save the changes.

⚠️ Security Note:

Refreshing credentials invalidates the old ones, so ensure your application is updated before the old credentials expire.

🧪 Testing & Verification

After completing the setup, test your webhook endpoint to ensure it can receive and process payloads correctly
Monitor your webhook logs to verify that events are being received and processed successfully
Implement proper error handling and logging in your webhook endpoint
Consider setting up monitoring and alerting for webhook delivery failures

🔧 Troubleshooting

If webhooks are not being received, check that your endpoint URL is accessible and returns a 200 status code
Verify that your webhook endpoint can handle the expected payload sizes and formats
Ensure your firewall and security settings allow incoming requests from IC Academy servers
Check your application logs for any errors during webhook processing