---
title: "Platform Integrations"
description: "The Platform Integrations module provides a robust framework for connecting to external services, managing credentials securely, performing automated checks, synchronizing employee data, and handli..."
last_updated: "2026-05-06T07:29:41.656037+00:00"
canonical_url: "https://www.doc0.dev/docs/49c89830-117b-4def-8edc-b5bcc50766e0/technical/section-5/platform-integrations"
---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [apps/api/src/integration-platform/controllers/task-integrations.controller.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/task-integrations.controller.ts)
- [apps/api/src/integration-platform/controllers/connections.controller.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/connections.controller.ts)
- [apps/api/src/integration-platform/controllers/checks.controller.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/checks.controller.ts)
- [apps/api/src/integration-platform/controllers/admin-integrations.controller.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/admin-integrations.controller.ts)
- [apps/api/src/integration-platform/controllers/oauth-apps.controller.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/oauth-apps.controller.ts)
- [apps/api/src/integration-platform/controllers/oauth.controller.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/oauth.controller.ts)
- [apps/api/src/integration-platform/controllers/sync.controller.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/sync.controller.ts)
- [apps/api/src/integration-platform/controllers/variables.controller.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/variables.controller.ts)
- [apps/api/src/integration-platform/controllers/webhook.controller.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/webhook.controller.ts)
- [apps/api/src/integration-platform/services/connection.service.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/connection.service.ts)
- [apps/api/src/integration-platform/services/auto-check-runner.service.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/auto-check-runner.service.ts)
- [apps/api/src/integration-platform/services/credential-vault.service.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/credential-vault.service.ts)
- [apps/api/src/integration-platform/repositories/provider.repository.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/repositories/provider.repository.ts)
- [apps/api/src/integration-platform/utils/credential-utils.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/utils/credential-utils.ts)
</details>

The Platform Integrations module provides a robust framework for connecting to external services, managing credentials securely, performing automated checks, synchronizing employee data, and handling webhooks. It abstracts the complexities of various authentication mechanisms (OAuth2, API Key, Custom) and offers a standardized way to interact with diverse third-party platforms. The system is designed to be extensible, allowing new integrations to be added via "manifests" that define their capabilities, authentication methods, and checks.

At its core, the module facilitates the creation and management of `Connections` between an organization and an `IntegrationProvider`. It ensures that sensitive `Credentials` are encrypted and handled safely, automatically refreshing OAuth tokens when necessary. Automated `Checks` can be run against these connections to validate configurations or monitor compliance, with results stored and associated with specific tasks. Additionally, the platform supports `Employee Synchronization` from HRIS/IDP systems and processes incoming `Webhooks` to react to external events.

## 1. Integration Providers and Manifests

Integration providers represent external services (e.g., AWS, Google Workspace, Rippling) that the platform can connect to. Each provider is defined by a "manifest" which outlines its capabilities, authentication requirements, available checks, and other metadata. The system dynamically loads these manifests to present available integrations and configure their behavior.

### 1.1 Provider Data Model

The `ProviderRepository` interacts with the `IntegrationProvider` Prisma model to store metadata about each provider, such as its slug, name, category, capabilities, and whether it's active. This allows the system to persist information about available integrations independently of their manifest definitions.


Sources: [apps/api/src/integration-platform/repositories/provider.repository.ts:10-40](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/repositories/provider.repository.ts#L10-L40), [apps/api/src/integration-platform/controllers/connections.controller.ts:40-45](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/connections.controller.ts#L40-L45)

### 1.2 Provider Listing and Details

The `ConnectionsController` exposes endpoints to list all available integration providers or retrieve details for a specific one. These endpoints aggregate information from the loaded manifests and, for OAuth providers, check if platform-level credentials have been configured.

#### API Endpoints

| Method | Path                                 | Description                                   |
| :----- | :----------------------------------- | :-------------------------------------------- |
| `GET`  | `/integrations/connections/providers` | List all available integration providers.     |
| `GET`  | `/integrations/connections/providers/:slug` | Get details for a specific provider.          |

Sources: [apps/api/src/integration-platform/controllers/connections.controller.ts:47-147](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/connections.controller.ts#L47-L147)

## 2. Connection Management

Connections represent an active link between an organization and an integration provider. The `ConnectionService` and `ConnectionRepository` manage the lifecycle and state of these connections.

### 2.1 Connection Lifecycle

A connection can transition through various states: `active`, `paused`, `error`, and `disconnected`. The system provides explicit actions to manage these states.


Sources: [apps/api/src/integration-platform/services/connection.service.ts:69-95](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/connection.service.ts#L69-L95)

### 2.2 Connection Creation and Updates

Creating a connection involves validating the provider, handling different authentication types (OAuth2, API Key, Custom), and storing credentials securely. For custom integrations like AWS, specific validation steps are performed before the connection is activated.


Sources: [apps/api/src/integration-platform/controllers/connections.controller.ts:182-259](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/connections.controller.ts#L182-L259), [apps/api/src/integration-platform/services/connection.service.ts:50-67](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/connection.service.ts#L50-L67)

#### API Endpoints

| Method | Path                                   | Description                                                              |
| :----- | :------------------------------------- | :----------------------------------------------------------------------- |
| `GET`  | `/integrations/connections`            | List connections for an organization.                                    |
| `GET`  | `/integrations/connections/:id`        | Get details for a specific connection.                                   |
| `POST` | `/integrations/connections`            | Create a new connection (API Key/Custom auth).                           |
| `POST` | `/integrations/connections/:id/pause`  | Pause a connection.                                                      |
| `POST` | `/integrations/connections/:id/resume` | Resume a paused connection.                                              |
| `POST` | `/integrations/connections/:id/disconnect` | Disconnect (soft delete) a connection.                                   |
| `DELETE` | `/integrations/connections/:id`        | Delete a connection permanently.                                         |
| `PATCH` | `/integrations/connections/:id`        | Update connection metadata (e.g., `connectionName`, `regions`).          |
| `POST` | `/integrations/connections/:id/test`   | Test a connection's credentials.                                         |
| `POST` | `/integrations/connections/:id/ensure-valid-credentials` | Ensure credentials are valid, refreshing OAuth tokens if needed.         |
| `PUT`  | `/integrations/connections/:id/credentials` | Update credentials for a custom auth connection.                         |

Sources: [apps/api/src/integration-platform/controllers/connections.controller.ts:150-484](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/connections.controller.ts#L150-L484)

<Callout title="AWS Credential Validation" variant="info">
For AWS connections, the `ConnectionsController` includes a specialized `validateAwsCredentials` method. This method attempts to assume an IAM role and verify Security Hub enablement across specified regions before a connection is established or updated. This ensures that the provided AWS credentials have the necessary permissions and that the required AWS services are active.
</Callout>
Sources: [apps/api/src/integration-platform/controllers/connections.controller.ts:262-390](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/connections.controller.ts#L262-L390)

## 3. Credential Management and Security

The `CredentialVaultService` is responsible for the secure storage, retrieval, and lifecycle management of integration credentials. It employs strong encryption and handles OAuth token refreshing.

### 3.1 Encryption Mechanism

All sensitive credentials are encrypted using AES-256-GCM with a derived key. This ensures that credentials are never stored in plain text.


Sources: [apps/api/src/integration-platform/services/credential-vault.service.ts:20-77](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/credential-vault.service.ts#L20-L77)

### 3.2 Credential Storage and Retrieval

The `CredentialVaultService` provides methods to store both OAuth tokens and API key/custom credentials. It manages credential versions, keeping a history and marking old versions as rotated.

#### Key Functions

*   `storeOAuthTokens(connectionId, tokens)`: Stores encrypted OAuth access and refresh tokens, along with their expiry.
*   `storeApiKeyCredentials(connectionId, credentials)`: Stores encrypted API key or custom credentials.
*   `getDecryptedCredentials(connectionId)`: Retrieves and decrypts the latest credentials for a given connection.
*   `rotateCredentials(connectionId, newCredentials)`: Marks current credentials as rotated and stores new ones.

Sources: [apps/api/src/integration-platform/services/credential-vault.service.ts:80-164](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/credential-vault.service.ts#L80-L164)

### 3.3 OAuth Token Refresh

For OAuth2 integrations, the `CredentialVaultService` automatically handles token refreshing when an access token is expired or nearing expiry. This ensures continuous operation without manual re-authentication.

```mermaid
sequenceDiagram
    participant App as "Application/Service"
    participant CV as "CredentialVaultService"
    participant ConnRepo as "ConnectionRepository"
    participant OAuthProvider as "OAuth Provider API"

    App->>CV: getValidAccessToken(connId, refreshConfig)
    CV->>CV: needsRefresh(connId)?
    alt Token needs refresh & refreshConfig provided
        CV->>CV: getRefreshToken(connId)
        CV->>OAuthProvider: POST /token (grant_type=refresh_token)
        OAuthProvider-->>CV: New Access/Refresh Tokens
        CV->>CV: storeOAuthTokens(connId, newTokens)
        CV->>ConnRepo: update(connId, {status: 'active'})
        CV-->>App: New Access Token
    else Token valid or refresh failed
        CV->>CV: getDecryptedCredentials(connId)
        CV-->>App: Current Access Token (or null if failed)
    end
```
Sources: [apps/api/src/integration-platform/services/credential-vault.service.ts:192-299](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/credential-vault.service.ts#L192-L299)

### 3.4 Credential Utilities

The `credential-utils.ts` file provides helper functions for normalizing credential values, especially when dealing with fields that might be single strings or arrays of strings.

*   `getStringValue(value)`: Extracts the first string from a `string | string[]` value.
*   `toStringCredentials(credentials)`: Converts a `{ [key: string]: string | string[] }` object to `{ [key: string]: string }`.

Sources: [apps/api/src/integration-platform/utils/credential-utils.ts:1-26](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/utils/credential-utils.ts#L1-L26)

## 4. OAuth Flow Management

The `OAuthController` orchestrates the OAuth 2.0 authorization code flow, enabling users to grant the platform access to their external accounts. This involves redirecting users to the OAuth provider, handling callbacks, and securely exchanging authorization codes for tokens.

### 4.1 OAuth State and Credentials

*   `OAuthStateRepository`: Stores temporary state parameters (`providerSlug`, `organizationId`, `userId`, `codeVerifier`, `redirectUrl`) during the OAuth flow to prevent CSRF attacks and maintain context.
*   `OAuthCredentialsService`: Manages platform-level (admin-configured) and organization-level (custom app) OAuth client credentials (`clientId`, `clientSecret`, `scopes`).

### 4.2 Starting the OAuth Flow

The `startOAuth` endpoint initiates the process by generating a unique state, constructing the authorization URL, and redirecting the user.

```mermaid
sequenceDiagram
    actor User
    participant App as "Client Application"
    participant API as "OAuthController"
    participant OCS as "OAuthCredentialsService"
    participant OSR as "OAuthStateRepository"
    participant OAuthProvider as "External OAuth Provider"

    User->>App: Click "Connect Integration"
    App->>API: POST /oauth/start {providerSlug, orgId, userId}
    API->>OCS: getCredentials(providerSlug, orgId)
    OCS-->>API: {clientId, clientSecret, scopes}
    API->>OSR: createOAuthState({providerSlug, orgId, userId, codeVerifier})
    OSR-->>API: {state, codeVerifier}
    API->>API: Build Authorization URL
    API-->>App: {authorizationUrl}
    App->>User: Redirect to authorizationUrl
    User->>OAuthProvider: Authorize App
    OAuthProvider-->>User: Redirect to callbackUrl with code & state
```
Sources: [apps/api/src/integration-platform/controllers/oauth.controller.ts:60-149](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/oauth.controller.ts#L60-L149)

### 4.3 OAuth Callback Handling

The `oauthCallback` endpoint receives the authorization code from the OAuth provider, validates the state, exchanges the code for access and refresh tokens, stores them, and then redirects the user back to the application.

```mermaid
sequenceDiagram
    actor User
    participant OAuthProvider as "External OAuth Provider"
    participant API as "OAuthController"
    participant OSR as "OAuthStateRepository"
    participant OCS as "OAuthCredentialsService"
    participant CVS as "CredentialVaultService"
    participant ConnS as "ConnectionService"
    participant ACR as "AutoCheckRunnerService"
    participant App as "Client Application"

    OAuthProvider->>API: GET /oauth/callback {code, state, error?}
    API->>OSR: findByState(state)
    OSR-->>API: OAuthState (or null)
    alt Invalid/Expired State or Error
        API->>API: Build Error Redirect URL
        API-->>User: Redirect to Error URL
    else Valid State
        API->>OCS: getCredentials(providerSlug, orgId)
        OCS-->>API: {clientId, clientSecret, scopes}
        API->>OAuthProvider: POST /token {code, redirect_uri, client_id, client_secret, code_verifier}
        OAuthProvider-->>API: Access/Refresh Tokens
        API->>ConnS: createConnection() or findByProviderAndOrg()
        ConnS-->>API: Connection
        API->>CVS: storeOAuthTokens(connection.id, tokens)
        API->>ACR: tryAutoRunChecks(connection.id)
        API->>API: Build Success Redirect URL
        API-->>User: Redirect to Success URL
    end
```
Sources: [apps/api/src/integration-platform/controllers/oauth.controller.ts:152-297](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/oauth.controller.ts#L152-L297)

### 4.4 Managing Custom OAuth Apps

The `OAuthAppsController` allows organizations to configure their own OAuth application credentials for a provider, overriding platform-level credentials. This is useful for providers where custom app creation is common or required.

#### API Endpoints

| Method | Path                                   | Description                                       |
| :----- | :------------------------------------- | :------------------------------------------------ |
| `GET`  | `/integrations/oauth-apps`             | List custom OAuth apps for an organization.       |
| `GET`  | `/integrations/oauth-apps/setup/:providerSlug` | Get OAuth app setup info for a provider.          |
| `POST` | `/integrations/oauth-apps`             | Save custom OAuth app credentials for an organization. |
| `DELETE` | `/integrations/oauth-apps/:providerSlug` | Delete custom OAuth app credentials.              |

Sources: [apps/api/src/integration-platform/controllers/oauth-apps.controller.ts:16-96](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/oauth-apps.controller.ts#L16-L96)

### 4.5 Admin-level OAuth Configuration

The `AdminIntegrationsController` provides administrative functions to configure platform-wide OAuth client credentials for providers. This is typically done once by platform administrators.

#### API Endpoints

| Method | Path                                   | Description                                       |
| :----- | :------------------------------------- | :------------------------------------------------ |
| `GET`  | `/admin/integrations`                  | List all integrations with credential status.     |
| `GET`  | `/admin/integrations/:providerSlug`    | Get details for a specific integration.           |
| `POST` | `/admin/integrations/credentials`      | Save platform credentials for an integration.     |
| `DELETE` | `/admin/integrations/credentials/:providerSlug` | Delete platform credentials for an integration.   |

Sources: [apps/api/src/integration-platform/controllers/admin-integrations.controller.ts:19-140](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/admin-integrations.controller.ts#L19-L140)

## 5. Automated Checks

The platform can run automated checks against integrated services to verify configurations, monitor compliance, or validate specific conditions. These checks are defined within the integration manifests.

### 5.1 Check Definition and Listing

Checks are defined within the `manifest.checks` array, often mapping to specific task templates. The `ChecksController` and `TaskIntegrationsController` provide ways to discover and list these checks.

#### API Endpoints

| Method | Path                                   | Description                                       |
| :----- | :------------------------------------- | :------------------------------------------------ |
| `GET`  | `/integrations/checks/providers/:providerSlug` | List available checks for a provider.             |
| `GET`  | `/integrations/checks/connections/:connectionId` | List available checks for a connection.           |
| `GET`  | `/integrations/tasks/template/:templateId/checks` | Get checks for a specific task template.          |
| `GET`  | `/integrations/tasks/:taskId/checks`   | Get checks for a specific task.                   |
| `GET`  | `/integrations/tasks/:taskId/runs`     | Get check run history for a task.                 |

Sources: [apps/api/src/integration-platform/controllers/checks.controller.ts:19-74](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/checks.controller.ts#L19-L74), [apps/api/src/integration-platform/controllers/task-integrations.controller.ts:35-132](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/task-integrations.controller.ts#L35-L132)

### 5.2 Running Checks

Checks can be triggered manually or automatically. The `runCheckForTask` and `runConnectionChecks` methods handle the execution, credential retrieval, and result storage.


Sources: [apps/api/src/integration-platform/controllers/task-integrations.controller.ts:135-309](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/task-integrations.controller.ts#L135-L309), [apps/api/src/integration-platform/controllers/checks.controller.ts:77-210](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/checks.controller.ts#L77-L210)

### 5.3 Auto-Check Runner

The `AutoCheckRunnerService` determines if checks can be automatically run for a connection (e.g., after creation or credential update) and triggers a background task via `Trigger.dev` for reliable execution.

#### Key Functions

*   `canAutoRunChecks(connectionId)`: Checks if a connection has checks defined and all required variables are configured.
*   `tryAutoRunChecks(connectionId)`: Triggers the `run-connection-checks` task if `canAutoRunChecks` returns true.

Sources: [apps/api/src/integration-platform/services/auto-check-runner.service.ts:12-89](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/auto-check-runner.service.ts#L12-L89)

## 6. Variable Management

Integrations can define variables that allow users to customize check behavior or provide configuration values. These variables can have static options or dynamic options fetched from the external service.

### 6.1 Variable Definition and Values

Variables are defined in the integration manifest at both the provider and check levels. The `VariablesController` allows retrieving these definitions and managing their values for a specific connection.

#### API Endpoints

| Method | Path                                   | Description                                       |
| :----- | :------------------------------------- | :------------------------------------------------ |
| `GET`  | `/integrations/variables/providers/:providerSlug` | Get all variables required for a provider's checks. |
| `GET`  | `/integrations/variables/connections/:connectionId` | Get variables for a specific connection (with current values). |
| `POST` | `/integrations/variables/connections/:connectionId` | Save variable values for a connection.            |

Sources: [apps/api/src/integration-platform/controllers/variables.controller.ts:32-132](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/variables.controller.ts#L32-L132)

### 6.2 Dynamic Options Fetching

For variables with dynamic options, the `VariablesController` can fetch these options from the external service using the connection's credentials. This is useful for populating dropdowns with values like AWS regions, user groups, or other configurable entities.


Sources: [apps/api/src/integration-platform/controllers/variables.controller.ts:135-249](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/variables.controller.ts#L135-L249)

## 7. Employee Synchronization

The `SyncController` provides functionality to synchronize employee data from various HRIS/IDP systems (e.g., Google Workspace, Rippling, Ramp, JumpCloud) into the platform. This ensures that the platform's user base is kept up-to-date with external systems.

### 7.1 Synchronization Process

The synchronization process typically involves:
1.  Retrieving valid credentials for the connection (refreshing OAuth tokens if necessary).
2.  Fetching a list of users from the external service.
3.  Identifying active, inactive, or suspended users.
4.  Creating new users and members in the platform for active external users.
5.  Reactivating existing members if they were previously deactivated but are now active externally.
6.  Deactivating members in the platform if they are inactive, suspended, or removed from the external system.


Sources: [apps/api/src/integration-platform/controllers/sync.controller.ts:25-885](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/sync.controller.ts#L25-L885)

### 7.2 Supported Sync Providers

The `SyncController` explicitly supports the following employee synchronization providers:

<Tabs items={["Google Workspace", "Rippling", "Ramp", "JumpCloud"]}>
<Tab value="Google Workspace">
*   **Endpoint**: `POST /integrations/sync/google-workspace/employees`
*   **Status Check**: `POST /integrations/sync/google-workspace/status`
*   **Details**: Fetches users via Admin SDK Directory API, handles OAuth token refresh, and manages user/member lifecycle based on Google Workspace user status (active/suspended).
</Tab>
<Tab value="Rippling">
*   **Endpoint**: `POST /integrations/sync/rippling/employees`
*   **Status Check**: `POST /integrations/sync/rippling/status`
*   **Details**: Fetches workers via Rippling V2 REST API, handles OAuth token refresh, and manages user/member lifecycle based on Rippling worker status. Includes a specific call to `mark_app_installed` as required by Rippling.
</Tab>
<Tab value="Ramp">
*   **Endpoint**: `POST /integrations/sync/ramp/employees`
*   **Status Check**: `POST /integrations/sync/ramp/status`
*   **Details**: Fetches users via Ramp Developer API, handles OAuth token refresh, and manages user/member lifecycle based on Ramp user status (active/inactive/suspended).
</Tab>
<Tab value="JumpCloud">
*   **Endpoint**: `POST /integrations/sync/jumpcloud/employees`
*   **Status Check**: `POST /integrations/sync/jumpcloud/status`
*   **Details**: Fetches users and their associated systems via JumpCloud API (v1 and v2), uses API key authentication, and manages user/member lifecycle based on JumpCloud user state.
</Tab>
</Tabs>
Sources: [apps/api/src/integration-platform/controllers/sync.controller.ts:25-885](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/sync.controller.ts#L25-L885)

### 7.3 Setting Employee Sync Provider

Organizations can configure which external system acts as their primary source for employee synchronization.

#### API Endpoints

| Method | Path                                   | Description                                       |
| :----- | :------------------------------------- | :------------------------------------------------ |
| `GET`  | `/integrations/sync/employee-sync-provider` | Get the current employee sync provider for an organization. |
| `POST` | `/integrations/sync/employee-sync-provider` | Set the employee sync provider for an organization. |

Sources: [apps/api/src/integration-platform/controllers/sync.controller.ts:888-963](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/sync.controller.ts#L888-L963)

## 8. Webhook Handling

The `WebhookController` is responsible for receiving and processing incoming webhooks from integrated services. It includes mechanisms for signature verification to ensure the authenticity and integrity of webhook payloads.

### 8.1 Webhook Processing Flow

When a webhook is received, the system first identifies the provider, verifies the connection, and then, if configured, validates the webhook's signature using a shared secret. If the signature is valid, the webhook payload is passed to the integration's custom handler for processing.


Sources: [apps/api/src/integration-platform/controllers/webhook.controller.ts:33-100](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/webhook.controller.ts#L33-L100)

### 8.2 Signature Verification

The `WebhookController` implements a robust signature verification process using HMAC. This protects against tampering and ensures that webhooks originate from trusted sources.

#### Key Functions

*   `extractSignature(headers, headerName)`: Extracts the signature string from request headers.
*   `parseSignatureValue(signature)`: Parses signature values that might include prefixes (e.g., `sha256=...`).
*   `verifyHmac(rawBody, secret, algorithm, providedSignature)`: Performs a timing-safe HMAC verification against the raw request body and a stored secret.

<Callout title="Security Best Practice" variant="success">
Using `timingSafeEqual` for comparing HMAC signatures is crucial to prevent timing attacks, where an attacker could deduce parts of the secret by measuring the time it takes for the comparison function to return.
</Callout>
Sources: [apps/api/src/integration-platform/controllers/webhook.controller.ts:18-30](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/webhook.controller.ts#L18-L30), [apps/api/src/integration-platform/controllers/webhook.controller.ts:102-132](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/webhook.controller.ts#L102-L132)

#### API Endpoints

| Method | Path                                   | Description                                       |
| :----- | :------------------------------------- | :------------------------------------------------ |
| `POST` | `/integrations/webhooks/:providerSlug/:connectionId` | Receives and processes incoming webhooks for a specific connection. |

Sources: [apps/api/src/integration-platform/controllers/webhook.controller.ts:33-100](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/webhook.controller.ts#L33-L100)

## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/49c89830-117b-4def-8edc-b5bcc50766e0/llms.txt) for all pages in this wiki.