Webhook Endpoint

Each webhook gets a unique public HTTPS URL. The URL contains two security tokens embedded directly: the webhook name and a 48-character secure code. Any HTTP client can POST JSON to this URL.

Authentication — Dual-Factor

Every request must pass two independent authentication checks:

The API key is stored as an SHA-256 hash in CH_Webhook__c.Enc_Api_Key__c. Validation rehashes the incoming key and compares. The plain key is never stored.

Field Mapping with JSONPath

Admins use the CH Mapping Ui LWC to visually connect JSON fields to Salesforce fields. Each mapping line stores a JSONPath expression (e.g. $.orders[*].id) in CH_Mapping__c.JsonPath_Expression__c.

At runtime, JSONPathEvaluator evaluates these expressions against the incoming JSON and extracts values. The JSONPath engine supports:

• Root $.field and nested $.parent.child access
• Array indexing $.items[0] and wildcard $.items[*]
• Filter expressions $.items[?(@.price > 10)]
• Recursive descent $..fieldName

AI Filter in Mapping

A built-in feature inside the CH Mapping UI that lets you filter specific rows from a JSON array using conditions. Only rows that match the filter will create Salesforce records. You can write the filter manually — or describe it in plain English and let AI generate it for you.

How to Use It — Step by Step

1. Open Webhook → Mapping

   Navigate to your webhook in ConnectHooks and open the CH Mapping UI.

2. Select a Salesforce Object

   Choose the target object (e.g. Contact) you want records created in.

3. Pick an Array Field from your JSON Schema and click "Apply Filter"

   Select a JSON array field as the data source (e.g. $.orders[*]).

4. Describe Your Filter in Plain English

   Type a natural-language condition — for example: "Get orders where amount > 1000".

5. Click "Get JSONPath"

   The AI generates the matching JSONPath filter expression (e.g. $.orders[?(@.amount > 1000)]) and drops it directly into your field mapping.

6. Review & Edit (Optional)

   You can manually adjust the generated expression in the UI before saving if needed.

7. Save

   The filter is stored on the mapping. At runtime, only matching rows from the JSON array will trigger record creation.

Mapping Validations

The CH Mapping UI runs several real-time validations to prevent invalid configurations before they reach the runtime engine. These checks fire automatically — no manual action needed.

1. Data Type Compatibility

ConnectHooks checks whether the JSON data type of the source field is compatible with the target Salesforce field type. Incompatible combinations are blocked immediately.

2. Array Filter Mismatch

All fields mapped to the same Salesforce object must share the same final array-level filter. Mixing different filters on the same object would cause conflicting row selection — ConnectHooks blocks this with an error toast.

3. Unsaved Changes Warning

If you have added mapping objects, dropped fields, or applied filters but have not yet clicked Save, ConnectHooks shows a warning before you leave. This prevents accidental loss of mapping work.

4. Schema Upload Clears All Mappings

Any new schema upload — even if it is the same JSON file — is treated as a full reset of the mapping configuration. This ensures the schema tree and mapped fields always stay in sync.

Record Creation

WebhookRuntimeService reads the CH_Mapping_Object__c tree and creates SObject records dynamically using Database.insert. It handles:

Form Submission Storage (Raw JSON Storage)

Optionally saves a copy of every incoming raw JSON payload into a Salesforce record, giving admins a complete audit trail of all webhook requests — successful or failed.

What Each Form Submission Record Stores

Custom Handler API

Developers can bypass the standard mapping engine by implementing the ICHCustomHandler interface and registering their Apex class name in the Custom_Handler_Class__c field on the corresponding webhook record. CH_Webhook__c is a Custom Object — each row represents one webhook integration. The Custom_Handler_Class__c field is a plain text field where you enter the fully-qualified Apex class name (e.g. MyHandler). When ConnectHooks receives a request for that webhook, it dynamically instantiates your class and calls execute(jsonPayload) instead of the built-in field mapping engine.

// Implement this interface in your Apex class
public class MyHandler implements xccch.ICHCustomHandler {
    public void execute(String jsonPayload) {
        // Parse the payload and do custom logic here
        Map<String,Object> data = (Map<String,Object>)
            JSON.deserializeUntyped(jsonPayload);
        // Create/update records as needed
    }
}

Custom Objects

CH Webhook (CH_Webhook__c) — Webhook Registry

CH Mapping Object (CH_Mapping_Object__c) — Target Object Config

CH Mapping (CH_Mapping__c) — Field-Level Mappings

Form Submission (Form_Submission__c) — Raw Payload Log

JSON Schema (JSON_Schema__c) — Validation Schema

Stores a JSON schema string linked to a webhook. Used by the runtime to validate required fields in incoming payloads before processing begins.

Custom Settings

ConnectHooks Config Settings (ConnectHooks_Config_Settings__c) — Hierarchy Custom Setting

Security Model

Additionally, the WebhookLimitTrigger enforces the creation limit at the database level — it cannot be bypassed via any interface, including Data Loader or direct API calls.

Permission Sets

Reading Form Submission (Form_Submission__c) Logs

Every webhook request (successful or failed) creates a Form_Submission__c record (if JSON storage is enabled). Check these fields:

❗ Common Errors & Fixes

Debugging JSONPath Expressions

Use the live preview in the CH Mapping Ui LWC — paste a sample JSON payload and click Test next to any mapping row. The JSONPathAPIController.evaluateJSONPath() method runs the expression and shows the extracted value.

You can also test manually using the developer console. Example:

// In Salesforce Developer Console (Anonymous Apex)
String json = '{"name":"John","email":"john@example.com"}';
String path = '$.email';
Object result = xccch.JSONPathEvaluator.evaluate(json, path);
System.debug(result); // → john@example.com