# 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:

```typescript
// 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](/krnl-studio/how-to-construct-a-workflow.md) 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](https://github.com/KRNL-Labs/salesforce-krnl) |
| HubSpot    | Event-driven workflow automation | [KRNL-Labs/hubspot-krnl](https://github.com/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](https://discord.gg/krnl-labs).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.krnl.xyz/enterprise-integration/custom-connectors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.