> For the complete documentation index, see [llms.txt](https://docs.keeper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeper.io/keeperpam/secrets-manager/integrations/salesforce-itsm.md).

# Salesforce ITSM

Salesforce integration that transforms Keeper Security events into actionable Service Cloud Cases in real-time.

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FRGG1pPIkk5VYmbM6aGgp%2Fkeeper%2Bsalesforce.png?alt=media&#x26;token=a5e75bc9-da97-48e2-8c0a-f2106148e8f9" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
This integration is
{% endhint %}

## Overview

Salesforce managed package that automatically converts Keeper Security alerts into Service Cloud Cases for streamlined incident management.

When security events occur in your Keeper environment (such as failed logins, vault transfers, or BreachWatch alerts), the package automatically creates Salesforce Cases for your IT and security teams to investigate and resolve.

### Key Features

* **Guided Setup Wizard** - Step-by-step setup assistant with progress tracking and auto-detection
* **Automated Case Creation** - Security alerts from Keeper automatically create Cases in Salesforce
* **Flexible Field Mapping** - Map Keeper alert data to any Case field (standard or custom)
* **Priority Rules** - Configure priority rules based on event types and categories
* **Secure Authentication** - Token-based webhook authentication
* **Admin Configuration UI** - Easy-to-use configuration interface for admins

***

## Installation

### Prerequisites

Before installing, ensure you have:

* Salesforce Enterprise, Performance, Unlimited, or Developer Edition
* System Administrator profile or equivalent permissions
* An active Keeper Security Enterprise subscription

### Install the Package

1. Navigate to the AppExchange listing for **Keeper ITSM**
2. Click **Get It Now**
3. Select your Salesforce org (Production or Sandbox)
4. Choose **Install for Admins Only** (recommended)
5. Click **Install** and wait for confirmation

{% hint style="info" %}
Installation typically takes 2-5 minutes. You will receive an email when complete.
{% endhint %}

***

## What Gets Installed

### Components Auto-Created on Install

| Component                 | Description                                                                                                      |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Custom Fields on Case** | 8 Keeper-specific fields for alert details                                                                       |
| **Case Layout**           | Keeper ITSM Layout with all Keeper fields; assign via Page Layout Assignment                                     |
| **Custom Objects**        | `Keeper_Field_Mapping__c`, `Keeper_Priority_Mapping__c` for configuration                                        |
| **Custom Settings**       | `Keeper_Webhook_Settings__c` for secure token storage and rate limiting                                          |
| **Permission Sets**       | Keeper ITSM Admin, Keeper ITSM User, Keeper Webhook User, Keeper Case Fields Access (auto-assigned to all users) |
| **Apex Classes**          | Webhook controller, incident service, mapping controllers                                                        |
| **Aura Component**        | Configuration UI (`KeeperConfigApp`)                                                                             |
| **Custom Tab**            | Keeper ITSM Config                                                                                               |
| **Lightning App**         | Keeper Security ITSM                                                                                             |

{% hint style="warning" %}
**Note:** The Salesforce Site for the webhook endpoint is **not** included in the package and must be created manually after installation. The Guided Setup wizard walks you through this process.
{% endhint %}

### Automatic Post-Install Configuration

On first install, the package automatically configures the following to minimize manual setup:

* **Permission Set**: Assigns `Keeper ITSM Admin` to the installing administrator
* **Field Mappings**: Creates 8 default mappings for all Keeper alert fields to their corresponding Case fields
* **Priority Rules**: Creates priority rules for common security event categories (login failures → High, role changes → Medium, etc.)
* **Authentication Token**: Generates an initial secure webhook token

{% hint style="success" %}
This means Steps 1, 3, 4, and 5 of the Guided Setup are **pre-configured automatically**. The only required manual steps are activating the Salesforce Site (Step 2) and configuring the Keeper Admin Console (Step 6).
{% endhint %}

### Custom Fields on Case

| Field Label              | API Name                      | Type           |
| ------------------------ | ----------------------------- | -------------- |
| Keeper Alert Name        | `Keeper_Alert_Name__c`        | Text (255)     |
| Keeper Event Type        | `Keeper_Event_Type__c`        | Text (255)     |
| Keeper Username          | `Keeper_User_Identifier__c`   | Text (255)     |
| Keeper Alert Timestamp   | `Keeper_Alert_Timestamp__c`   | Date/Time      |
| Keeper IP Address        | `Keeper_IP_Address__c`        | Text (50)      |
| Keeper Category          | `Keeper_Category__c`          | Text (100)     |
| Keeper Alert Description | `Keeper_Alert_Description__c` | Long Text Area |
| Keeper Client Version    | `Keeper_Client_Version__c`    | Text (100)     |

### Permission Sets

| Permission Set          | Purpose                                                            |
| ----------------------- | ------------------------------------------------------------------ |
| **Keeper ITSM Admin**   | Full access to configuration UI, field mappings, priority mappings |
| **Keeper ITSM User**    | Read access to Keeper Case fields                                  |
| **Keeper Webhook User** | Used by site guest user for webhook processing                     |

***

## Post-Installation Setup

After the package is installed, complete the configuration using the **Guided Setup** wizard or follow the manual steps below.

{% hint style="success" %}
**Recommended:** Use the **Guided Setup** tab in the Keeper ITSM Config page. It provides step-by-step instructions with automatic progress tracking and will detect which steps are already complete.
{% endhint %}

### Using Guided Setup (Recommended)

1. Open the **App Launcher** (9-dot grid icon)
2. Search for and select **Keeper ITSM Config**
3. The **Guided Setup** tab opens by default, showing your setup progress
4. Follow the numbered steps - completed steps show a green checkmark
5. Click the action buttons to complete each step

The Guided Setup wizard automatically detects:

* Whether the Salesforce Site is active
* Whether the site guest user has proper webhook permissions
* Whether an authentication token has been generated
* How many field mappings are configured
* How many priority rules are configured

#### Setup Steps

<table><thead><tr><th width="78.828125">Step</th><th>Name</th><th width="224.328125">Description</th><th width="109.40625">Auto-Detected</th><th>Auto-Configured</th></tr></thead><tbody><tr><td>1</td><td>Assign Permission Sets</td><td>Assign permission sets to admins and users who need access</td><td>Yes</td><td>Yes (admin assigned on install)</td></tr><tr><td>2</td><td>Activate Salesforce Site</td><td>Create and activate the webhook endpoint site</td><td>Yes</td><td>No (manual)</td></tr><tr><td></td><td>Configure Webhook Permissions</td><td>Assign guest user permissions for webhook processing</td><td>Yes</td><td>One-click button</td></tr><tr><td>3</td><td>Generate Authentication Token</td><td>Create a secure token for webhook authentication</td><td>Yes</td><td>Yes (generated on install)</td></tr><tr><td>4</td><td>Configure Field Mappings</td><td>Map Keeper alert fields to Case fields</td><td>Yes</td><td>Yes (8 defaults created)</td></tr><tr><td>5</td><td>Configure Priority Rules</td><td>Set Case priority based on event types</td><td>Yes</td><td>Yes (defaults created)</td></tr><tr><td>6</td><td>Configure Keeper Admin Console</td><td>Add webhook URL in Keeper (external step)</td><td>No</td><td>No (external)</td></tr><tr><td>7</td><td>Test Integration</td><td>Verify the integration by creating a test Case</td><td>Manual</td><td>No</td></tr></tbody></table>

#### Progress Tracking

* The progress ring shows the percentage of core steps completed (Steps 2-5, including guest user configuration)
* Completed steps display a green checkmark
* Pending steps show a numbered icon
* Optional steps are marked with an "Optional" badge

#### Testing from Guided Setup

Click the **Run Test** button in Step 7 to create a test Case directly from the wizard. This verifies that:

* The Salesforce Site is properly configured
* Field mappings are working correctly
* Priority rules are being applied

{% hint style="info" %}
The test creates an actual Case record with Origin "Keeper Security" that you can view and delete afterward.
{% endhint %}

***

### Manual Setup Steps

If you prefer manual configuration, follow these steps:

#### Step 1: Assign Permission Sets

{% hint style="success" %}
The installing administrator is **automatically assigned** the `Keeper ITSM Admin` permission set during installation. Assign it to additional administrators as needed.
{% endhint %}

Assign the **Keeper ITSM Admin** permission set to all users who need to configure the integration:

1. Go to **Setup** → **Permission Sets**
2. Click **Keeper ITSM Admin**
3. Click **Manage Assignments** → **Add Assignments**
4. Select the administrator users and click **Assign**

Additionally, assign the **Keeper ITSM User** permission set to users who need to view Keeper alert data on Cases:

1. Go to **Setup** → **Permission Sets**
2. Click **Keeper ITSM User**
3. Click **Manage Assignments** → **Add Assignments**
4. Select the users and click **Assign**

<div><figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2F5NRDN7afzGToHHJyBjl2%2FScreenshot%202026-02-02%20at%204.36.16%E2%80%AFPM.png?alt=media&#x26;token=c4c7891f-4ecf-4de9-ae6b-b596d5f39f0a" alt=""><figcaption></figcaption></figure> <figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FlJUMsLkHe1O9LPtrnMlZ%2FScreenshot%202026-02-02%20at%204.36.30%E2%80%AFPM.png?alt=media&#x26;token=2187f510-9952-450d-8c65-cacdc9c45849" alt=""><figcaption></figcaption></figure> <figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2Ffr4zToqcprGXC8L6vGFh%2FScreenshot%202026-02-02%20at%204.38.29%E2%80%AFPM.png?alt=media&#x26;token=eb17739d-cb82-4c37-a231-2ce1f1b389f8" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
**Keeper ITSM Admin** provides full configuration access. **Keeper ITSM User** provides read access to Keeper fields on Cases for support agents and other non-admin users.
{% endhint %}

#### Step 2: Create and Activate the Salesforce Site

The webhook endpoint requires an active Salesforce Site. This must be created manually (Sites cannot be included in managed packages).

1. Go to **Setup** → **Sites**
2. If you don't have a Sites domain registered, register one first (e.g., `your-company`)
3. Click **New** to create a new site with these settings:
   * **Site Label**: `KeeperWebhook`
   * **Site Name**: `KeeperWebhook`
   * **Active Site Home Page**: Select any Visualforce page (e.g., your org's default)
   * Leave other settings as defaults
4. Click **Save**, then **Activate** the site
5. Note the **Secure Web Address (HTTPS)** - you'll need this for the Keeper Admin Console

{% hint style="warning" %}
The Site URL varies by org. It typically follows this format: `https://[your-domain].my.salesforce-sites.com/KeeperWebhook`
{% endhint %}

**Configure Webhook Permissions for Guest User**

After creating and activating the site, the site's guest user needs permissions to process webhooks.

**Option A: Use Guided Setup (Recommended)**

1. Return to **Keeper ITSM Config** → **Guided Setup** tab
2. In Step 2, click the **Configure Webhook Permissions** button
3. The system automatically assigns the `Keeper Webhook User` permission set to the site guest user

**Option B: Manual Configuration**

1. Go to **Setup** → **Permission Sets** → **Keeper Webhook User**
2. Click **Manage Assignments** → **Add Assignment**
3. Find and select the guest user associated with your KeeperWebhook site (the user name will contain "KeeperWebhook" or "Keeper")
4. Click **Assign**

{% hint style="info" %}
The **Configure Webhook Permissions** button in Guided Setup is the easiest approach - it automatically finds the site guest user and assigns the correct permission set in one click.
{% endhint %}

#### Step 3: Retrieve Authentication Token

{% hint style="success" %}
A secure authentication token is **automatically generated** during package installation. You only need to retrieve it.
{% endhint %}

1. Open the **App Launcher** (9-dot grid icon)
2. Search for and select **Keeper ITSM Config**
3. On the **Webhook Setup** tab, click **Reveal** to view the token, then **Copy** it
4. If you need a fresh token, click **Generate New Token**

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FZSwqgru4HLQYXEpLFJ4U%2FScreenshot%202026-03-30%20at%2012.23.01%E2%80%AFPM.png?alt=media&amp;token=e0716999-002c-45e9-b8e1-9a82fca2efce" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
Store the token securely. You'll need it to configure the Keeper Admin Console.
{% endhint %}

#### Step 4: Configure Keeper Admin Console

1. Log in to the [Keeper Admin Console](https://keepersecurity.com/console/#login)
2. Navigate to **Reporting & Alerts**
3. Go to **Alerts** → **Add Alert** and select the alert types to monitor
4. Go to **Alerts** → **Add Recipient**
5. Select **Webhook** as the recipient type
6. Enter the full URL with token:

```
https://[your-site-url]/services/apexrest/KeeperITSM/keeper/webhook?token=YOUR_TOKEN_HERE
```

{% hint style="info" %}
**Important:** The URL must include the `KeeperITSM/` namespace prefix before `keeper/webhook`. The complete webhook URL (with namespace) is shown on the **Webhook Setup** tab of Keeper ITSM Config - copy it from there to avoid errors.
{% endhint %}

7. Save the configuration

#### Add Keeper Fields to Case Layout

The package includes a pre-configured **Keeper ITSM Layout** with all Keeper fields. To use it:

**Option A: Assign the Keeper ITSM Layout (Recommended)**

1. Go to **Setup** → **Object Manager** → **Case** → **Page Layouts**
2. Click **Page Layout Assignment**
3. For each profile that should see Keeper alert details, assign **Keeper ITSM Layout**
4. Click **Save**

**Option B: Add Keeper fields to your existing layout**

1. Go to **Setup** → **Object Manager** → **Case** → **Page Layouts**
2. Click your Case layout (e.g. Case Layout) → **Edit**
3. Add a new section (e.g. "Keeper Security Details")
4. Drag these 8 Keeper fields into the section: Keeper Alert Name, Keeper Event Type, Keeper Category, Keeper Alert Timestamp, Keeper Username, Keeper IP Address, Keeper Client Version, Keeper Alert Description
5. Click **Save**

***

## Configuration

Access the configuration page by opening the **App Launcher** and searching for **Keeper ITSM Config**. The page has four tabs: Guided Setup, Webhook Setup, Field Mapping, and Priority Mapping.

{% hint style="info" %}
You must have the **Keeper ITSM Admin** permission set or **System Administrator** profile to access the configuration page.
{% endhint %}

### Webhook Setup

The Webhook Setup tab provides the URL and authentication token needed to configure Keeper to send alerts to Salesforce.

#### Webhook URL

The webhook URL is displayed on the configuration page. Copy this URL to use in the Keeper Admin Console.

**URL Format:**

```
https://[your-domain].my.salesforce-sites.com/KeeperWebhook/services/apexrest/KeeperITSM/keeper/webhook
```

{% hint style="info" %}
The URL includes the `KeeperITSM/` namespace prefix. The exact URL for your org is displayed on the Webhook Setup tab - always copy it from there.
{% endhint %}

#### Authentication Token

* Click **Reveal** to display the full token
* Click **Copy** to copy the token to clipboard
* Click **Generate New Token** to create a new token

{% hint style="danger" %}
Generating a new token immediately invalidates the previous token. Update the Keeper Admin Console with the new token right away to avoid service interruption.
{% endhint %}

#### Full Webhook URL with Token

Append the token as a query parameter:

```
https://[your-site-url]/services/apexrest/KeeperITSM/keeper/webhook?token=YOUR_TOKEN_HERE
```

### Field Mapping

Field Mapping allows you to control which Keeper alert data populates which Salesforce Case fields.

#### Available Keeper Fields

| Keeper Field      | API Name         | Description                             |
| ----------------- | ---------------- | --------------------------------------- |
| Alert Name        | `alert_name`     | Name of the alert rule that triggered   |
| Audit Event Type  | `audit_event`    | Event type code (e.g., `login_failure`) |
| Username          | `username`       | User who triggered the event            |
| Description       | `description`    | Alert description text                  |
| Timestamp         | `timestamp`      | When the event occurred (ISO 8601)      |
| Remote IP Address | `remote_address` | IP address of the request origin        |
| Category          | `category`       | Event category                          |
| Client Version    | `client_version` | Keeper client version                   |

#### Adding a Field Mapping

1. Navigate to the **Field Mapping** tab
2. Select a **Keeper Field** from the dropdown
3. Select a **Salesforce Case Field** from the dropdown
4. Click **Add Mapping**

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FHjHSZuD6oxK121p5s9V1%2FScreenshot%202026-02-02%20at%204.45.45%E2%80%AFPM.png?alt=media&#x26;token=2a3da9c4-361d-4333-b4f5-78ecebf1c702" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Each Salesforce field can only be mapped to one Keeper field. Adding a duplicate mapping will replace the existing one.
{% endhint %}

#### Recommended Mappings

| Keeper Field      | Recommended Case Field   |
| ----------------- | ------------------------ |
| Alert Name        | Keeper Alert Name        |
| Audit Event Type  | Keeper Event Type        |
| Username          | Keeper Username          |
| Timestamp         | Keeper Alert Timestamp   |
| Remote IP Address | Keeper IP Address        |
| Category          | Keeper Category          |
| Description       | Keeper Alert Description |
| Client Version    | Keeper Client Version    |

#### Managing Mappings

* **Toggle Active/Inactive** - Use the toggle switch to enable or disable a mapping
* **Search** - Use the search box to filter mappings
* **Delete** - Click the delete icon to remove a mapping
* **Pagination** - Navigate through mappings using the page controls

#### Default Behavior (No Mappings Configured)

If no field mappings are configured, the package applies these defaults:

| Field       | Default Value                                       |
| ----------- | --------------------------------------------------- |
| Subject     | `[Alert Name]: [Event Type]`                        |
| Description | Full alert details in text format                   |
| Origin      | `Keeper Security`                                   |
| Status      | `New`                                               |
| Priority    | Determined by Priority Mapping rules (default: Low) |

### Priority Mapping

Priority Mapping allows you to automatically set Case priority based on the type of security event.

#### How Priority Matching Works

When a Keeper alert arrives, the system:

1. Checks for an **exact match** with configured event patterns
2. If no exact match, checks for **partial/contains matches**
3. If no match found, assigns default priority: **Low**

#### Adding Priority Rules

**Method 1: Category + Event Selection**

1. Navigate to the **Priority Mapping** tab
2. Select a **Category** from the dropdown
3. Optionally select a specific **Event** (leave empty to map ALL events in that category)
4. Select the **Priority**
5. Click **Add Rule**

{% hint style="info" %}
Leave the Event field empty to map ALL events in the selected category at once. This is useful for quickly setting up priority rules for entire categories.
{% endhint %}

**Method 2: Quick Add Buttons**

Use the Quick Add buttons to add common security rules:

| Button                    | What it Creates                                                                                 |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| **Security → High**       | BreachWatch alerts, vault transfers, user deletions, 2FA failures, KeeperAI critical/high risks |
| **Login Failures → High** | Failed logins, failed console logins, IP blocks, auth failures                                  |
| **Role Changes → Medium** | Role additions/removals, team changes, permission changes, user locks                           |
| **Normal Ops → Low**      | Normal logins, record operations, password copies, exports/imports                              |

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FZ8g552pMDkJwzakvZKCp%2FScreenshot%202026-02-02%20at%204.45.54%E2%80%AFPM.png?alt=media&#x26;token=ca96cb18-a0e4-42f0-a4e5-af2631a5ff31" alt=""><figcaption></figcaption></figure>

#### Event Categories Reference

The package supports 17 event categories with over 300 events from Keeper Security.

For the complete list of event types and their descriptions, refer to [Reporting, Alerts & SIEM](/enterprise-guide/event-reporting/event-descriptions.md)

{% hint style="info" %}
The Salesforce ITSM package includes all event types from Keeper's Event Reporting documentation as of the current package version.
{% endhint %}

#### Recommended Priority Configuration

| Event Types                                                 | Recommended Priority |
| ----------------------------------------------------------- | -------------------- |
| Vault transfers, Account deletions, 2FA failures, IP blocks | **High**             |
| Login failures, BreachWatch detections, KeeperAI alerts     | **High**             |
| Role changes, Permission changes, User locks                | **Medium**           |
| Record views, Password copies, Normal logins                | **Low**              |

***

## Testing the Integration

### Option 1: Use the Built-in Test (Recommended)

The easiest way to test the integration:

1. Go to **Keeper ITSM Config** → **Guided Setup** tab
2. Scroll to **Step 7: Test Integration**
3. Click **Run Test**
4. If successful, a test Case will be created and a link will appear

This creates a Case with:

* Subject: "Guided Setup Test Alert: test\_event"
* Origin: "Keeper Security"
* All configured field mappings applied

### Option 2: Send a Test Webhook via cURL/Postman

Use cURL or Postman to send a test webhook:

```bash
curl -X POST \
  'https://[your-site-url]/services/apexrest/KeeperITSM/keeper/webhook?token=YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "alert_name": "Test Alert",
    "audit_event": "login_failure",
    "username": "test.user@example.com",
    "description": "Test alert from manual trigger",
    "timestamp": "2025-01-30T10:30:00Z",
    "remote_address": "192.168.1.100",
    "category": "Login",
    "client_version": "16.10.0"
  }'
```

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2Fz9Cpa5QQsXqnnbE8d7np%2FScreenshot%202026-02-02%20at%204.52.03%E2%80%AFPM.png?alt=media&#x26;token=b3b6d8ae-3eb0-458a-a551-306a7eea03ed" alt=""><figcaption></figcaption></figure>

### Expected Responses

**Success (HTTP 200):**

```json
{
  "success": true,
  "caseId": "500XXXXXXXXXXXX"
}
```

**Authentication Error (HTTP 401):**

```json
{
  "success": false,
  "errorCode": "ERR_001",
  "message": "Unauthorized"
}
```

**Invalid Payload (HTTP 400):**

```json
{
  "success": false,
  "errorCode": "ERR_002",
  "message": "Invalid request format"
}
```

**Rate Limited (HTTP 429):**

```json
{
  "success": false,
  "errorCode": "ERR_004",
  "message": "Too many requests. Please try again later."
}
```

**Processing Error (HTTP 500):**

```json
{
  "success": false,
  "errorCode": "ERR_003",
  "message": "An error occurred processing the request"
}
```

***

## Troubleshooting

### Cases Not Being Created

| Issue                         | Solution                                                                                                                                                                                                    |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Webhook URL missing namespace | The URL must include the `KeeperITSM/` namespace prefix: `/services/apexrest/KeeperITSM/keeper/webhook`. Copy the exact URL from the Webhook Setup tab.                                                     |
| HTTP 404 on webhook URL       | Verify the URL includes the `KeeperITSM/` namespace prefix. Without it, Salesforce cannot find the endpoint.                                                                                                |
| Token invalid                 | Generate a new token and update Keeper Admin Console                                                                                                                                                        |
| Site not active               | Go to Setup → Sites and activate the KeeperWebhook site                                                                                                                                                     |
| HTTP 403 / "FORBIDDEN"        | The site guest user lacks webhook permissions. Use the **Configure Webhook Permissions** button in Guided Setup Step 2, or manually assign the `Keeper Webhook User` permission set to the site guest user. |
| Guest user permissions lost   | After certain org changes, guest user permissions may need to be reassigned. Use the **Configure Webhook Permissions** button in Guided Setup.                                                              |
| Rate limit lockout (HTTP 429) | Wait 5 minutes for the lockout to expire, then retry with a valid token                                                                                                                                     |

### "Access Denied" on Configuration Page

**Cause:** User doesn't have the required permission set.

**Solution:**

1. Go to **Setup** → **Permission Sets** → **Keeper ITSM Admin**
2. Click **Manage Assignments** → **Add Assignment**
3. Select the user and click **Assign**

### Field Data Not Appearing on Cases

| Issue                     | Solution                                                            |
| ------------------------- | ------------------------------------------------------------------- |
| Mapping not active        | Ensure the toggle is ON for the mapping                             |
| Field not in allowed list | Only whitelisted fields can be mapped (see `KeeperIncidentService`) |
| FLS permissions           | Verify the guest user profile has create permission on the field    |

### Incorrect Priority Being Assigned

**Priority matching order:**

1. Exact match rules are evaluated first
2. Partial/contains matches are evaluated second
3. Default priority is **Low** if no rules match

**Tip:** Create specific event rules before broad category rules.

### "Closed" Status Not Showing on Cases

**Cause:** By default, Salesforce hides closed statuses from the Case Status picklist to prevent accidental closure.

**Solution:**

1. Go to **Setup** → **Support Settings**
2. Find the setting **"Show Closed Statuses in Case Status Field"**
3. Check the box to enable it
4. Click **Save**

{% hint style="info" %}
This is a Salesforce org-wide setting that affects all Cases, not just those created by Keeper ITSM.
{% endhint %}

***

## Security Considerations

### Token Security

* Tokens are generated using cryptographically secure AES-128 random generation
* Tokens are stored in protected custom settings (not visible in standard queries)
* Token validation uses constant-time comparison (HMAC + XOR) to prevent timing attacks
* Regenerate tokens periodically as a security best practice
* Never share tokens in unsecured channels

### Rate Limiting

The webhook endpoint includes brute-force protection:

* After **5 consecutive failed** authentication attempts, the endpoint enters a **5-minute lockout**
* During lockout, all requests are rejected with HTTP 429 (Too Many Requests), even those with valid tokens
* A successful authentication immediately resets the failed attempt counter
* The lockout expires automatically after 5 minutes

{% hint style="warning" %}
If your Keeper Admin Console is sending alerts with an outdated token, those requests will count as failed attempts and may trigger a lockout. Always update the token in Keeper immediately after generating a new one. The lockout automatically clears after 5 minutes.
{% endhint %}

### Data Security

* All webhook requests require valid token authentication
* Error messages are sanitized to prevent information disclosure
* CRUD/FLS checks are enforced on all database operations
* Field mapping uses a whitelist approach for allowed fields

### Audit Trail

* All webhook requests are logged in Salesforce debug logs
* Cases created via webhook have `Origin = Keeper Security` for identification
* Failed authentication attempts are logged for security review

### Guest User Security

The site guest user is granted minimal permissions via the `Keeper Webhook User` permission set:

* **Apex Access**: Only webhook-related classes (`KeeperWebhookController`, `KeeperIncidentService`, `KeeperTokenService`)
* **Object Access**: Create-only on Case, Read-only on mapping objects (`Keeper_Field_Mapping__c`, `Keeper_Priority_Mapping__c`)
* **Field Access**: Limited to required Case fields

{% hint style="info" %}
Guest user permissions are managed via the `Keeper Webhook User` permission set. Use the **Configure Webhook Permissions** button in Guided Setup to assign this permission set to the site guest user automatically.
{% endhint %}

***

## FAQ

**Q: Can I use this with Salesforce sandbox?**

A: Yes, install the package in sandbox for testing. Use separate tokens for sandbox and production environments.

**Q: How do I upgrade to a new package version?**

A: Install the new version from AppExchange. Your configurations (mappings, tokens) are preserved during upgrades.

**Q: What Keeper events can trigger alerts?**

A: Any event type configured in Keeper Admin Console's Reporting & Alerts section.

**Q: Is the webhook endpoint secure?**

A: Yes. All requests require a valid authentication token. The endpoint uses HTTPS, error messages don't expose internal system details, token validation uses constant-time comparison to prevent timing attacks, and rate limiting protects against brute-force token guessing (lockout after 5 failed attempts).

**Q: Can I customize the Case Subject format?**

A: Currently, the default format is `[Alert Name]: [Event Type]`. Map the `alert_name` or `audit_event` fields to the Subject field for custom behavior.

**Q: What happens if the token is compromised?**

A: Immediately generate a new token from the Webhook Setup tab. The old token is invalidated instantly. Update the Keeper Admin Console with the new token.

**Q: Why am I getting HTTP 404 "Not Found" on the webhook URL?**

A: The webhook URL must include the `KeeperITSM/` namespace prefix. The correct format is `/services/apexrest/KeeperITSM/keeper/webhook`. Copy the exact URL from the **Webhook Setup** tab to avoid errors.

**Q: Why am I getting HTTP 403 "FORBIDDEN" on the webhook?**

A: The site guest user doesn't have permission to execute the webhook Apex classes. Go to **Keeper ITSM Config** → **Guided Setup** → **Step 2** and click the **Configure Webhook Permissions** button to fix this automatically.

**Q: Does the package automatically configure anything on install?**

A: Yes. The post-install script automatically assigns the Admin permission set, creates default field mappings, creates priority rules, and generates an authentication token. You only need to manually create the Salesforce Site and configure the Keeper Admin Console.

**Q: Why am I getting HTTP 429 "Too many requests" errors?**

A: The webhook endpoint has rate limiting that locks out after 5 consecutive failed authentication attempts for 5 minutes. This typically happens when the token in Keeper Admin Console is outdated. Wait 5 minutes for the lockout to expire, then update the token in Keeper Admin Console to match the current token in Salesforce.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.keeper.io/keeperpam/secrets-manager/integrations/salesforce-itsm.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
