Custom Connectors

Overview

You can build a custom connector using the KRNL SDK, KRNL Studio, and standard HTTP workflow steps. This page walks you through the architecture, patterns, and implementation details based on how we built the Salesforce and HubSpot connectors.

Integration Architecture Pattern

1. Authenticate — Use the HTTP executor to connect to your platform's API

2. Trigger — Define what events should initiate a KRNL workflow

3. Transform — Map platform data formats to KRNL workflow inputs

4. Attest — Let the Attestor sign all platform API calls and responses

5. Respond — Deliver signed results back to your platform or to downstream systems

Building Your Own Connector: Step-by-Step

Step 1: Define the Integration Boundary

Ask these questions before writing code:

Question	Example Answers
What platform event triggers the workflow?	Record created, file uploaded, stage changed, form submitted
What data does the workflow need from the platform?	User identity, record fields, file content, timestamps
What external services does the workflow call?	Internal APIs, third-party verification, AI models
What is the final verified output?	A hash, a status, a transformed record, a credential
Where does the proof get consumed?	Back to the platform, to a downstream system, to a compliance archive

Step 2: Build the Platform Interface

For UI-driven integrations (like Salesforce):

• Create a native component using the platform's component framework

• Handle authentication via OAuth or API keys

• Capture user actions and forward to your backend

For event-driven integrations (like HubSpot):

• Register a webhook endpoint in the platform

• Validate incoming webhooks (signature, timestamp, nonce)

• Queue the request for async processing

Step 3: Build the Backend Bridge

Your backend acts as a translator between platform conventions and KRNL workflow inputs:

// Example: Transform platform webhook to KRNL workflow request
function transformHubSpotWebhook(payload: HubSpotWebhook): WorkflowRequest {
  return {
    chain_id: 11155111,
    sender: payload.objectId,
    target: {
      contract: process.env.TARGET_CONTRACT,
      function: "submitComplianceCheck((uint256,string,string,uint256,string),string)",
      authData_result: "${construct-compliance-proof.result}",
      parameters: [
        { name: "dealId", type: "string", value: payload.objectId }
      ]
    },
    workflow: {
      name: "hubspot-compliance-check",
      steps: [
        // ... steps defined above
      ]
    }
  };
}

Step 4: Define the KRNL Workflow

Use KRNL Studio or write DSL directly. Follow these patterns: Store platform credentials as Attestor secrets, never in workflow definitions. Follow this page to build a KRNL workflow

Your backend should:

1. Trigger the KRNL workflow using the RPC link

2. Update the platform record with the verified result

3. Emit an audit event with the attestation hash for compliance

4. Handle failures gracefully (retry, alert, fallback)

Security Best Practices

Credential Management

Do	Don't
Store platform API keys as Attestor secrets	Hardcode credentials in workflow definitions
Rotate secrets via Attestor updates	Share secrets across multiple workflows
Use environment variables for URLs	Expose internal endpoints in public repos
Validate webhook signatures	Trust webhook payloads without verification

Data Handling

Do	Don't
Hash sensitive content before anchoring	Store raw PII on-chain or in attestor logs
Apply watermarks server-side	Rely on client-side watermarking that can be bypassed
Log access events with user identity	Log anonymous events that cannot be audited
Encrypt data in transit and at rest	Send sensitive data over unencrypted channels

Error Handling

Scenario	Response
Platform API timeout	Retry with exponential backoff; alert after 3 failures
KRNL Node unavailable	Queue request; notify operations team on Discord
Attestor signature invalid	Reject result; do not update platform state; trigger incident
Webhook replay detected	Deduplicate by intent ID; log and alert

Example Repositories

Platform	Pattern	Repository
Salesforce	Document-centric UI integration	KRNL-Labs/salesforce-krnl
HubSpot	Event-driven workflow automation	KRNL-Labs/hubspot-krnl

Best Practices

• Store platform credentials as Attestor secrets, never in workflow definitions

• Use environment variables for endpoint URLs

• Include replay protection with intent IDs and deadlines

• Emit events for all platform interactions for auditability

Need Help?

Contact our enterprise team for architecture reviews and custom connector development on Discord.