Developer Settings

Query request data and subscribe to real-time events using ClearFeed APIs

These settings empower you to securely verify the authenticity of incoming requests and receive real-time updates from ClearFeed on your preferred endpoint.

With the Signing Secret and Events API Subscription, you can seamlessly integrate ClearFeed into your applications and receive timely updates to stay in sync with the latest changes and activities.

Personal Access Token

ClearFeed's Personal Access Token (PAT) is a bearer token that provides authentication for users when making API calls. It offers a secure way to access and manage resources without exposing your primary credentials.

Key Facts

1. Not Present By Default: The PAT is not generated automatically for regular API use. It must be manually created, except when ClearFeed creates or reuses one during the remote MCP OAuth flow.

2. One Token Per User: At any given point in time, only one token is available per user.

3. Token Scope: A token can be generated with either Read-only or Read & Write access.

4. Deletion and Regeneration: If there are concerns about security, if a token is misplaced, or if you need to change its access level, delete the existing token and generate a new one.

Create Token

Go to the Developer Settings page and click Generate Token to create a new token. Choose the least-privileged access level that fits your use case:

• Read-only: Use this for reporting, analytics, lookups, and integrations that should not modify ClearFeed data.

• Read & Write: Use this for integrations that create or update requests, customers, custom fields, collections, or other ClearFeed data.

Existing tokens created before scope selection was available continue to have read and write access.

Token Scopes

ClearFeed decides whether an API endpoint requires read-only or read/write access from the HTTP method, unless the endpoint explicitly defines a different scope:

Endpoint type	Scope required
GET, HEAD, and OPTIONS endpoints	Read-only
POST, PUT, PATCH, and DELETE endpoints	Read & Write

The following POST endpoints are exceptions and can be called with a read-only token:

• POST /v1/rest/insights/query

• POST /v1/rest/customers/search

Use Token

When making API calls to ClearFeed, include the token in the Authorization header of your request:

Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN

Replace YOUR_PERSONAL_ACCESS_TOKEN with the token you generated.

Delete and Regenerate Token

If you ever feel your token has been compromised, or you want to generate a new one:

1. Go to Developer Settings page.

2. Click on the delete icon against the existing token.

3. Generate a new one if required.

Never Share: Treat your personal access token like a password. Do not share it, expose it in client-side code, or store it in insecure locations. For added security, consider periodically deleting and regenerating your token.

Automatic Token Revocation

When a Slack user is deleted or deactivated from the workspace, their ClearFeed API tokens are automatically revoked as a security measure.

• This revocation runs periodically (not instantaneous)

• Account admins are notified when tokens are revoked due to user deactivation/deletion

• This prevents former workspace members from retaining API access after they leave

For additional security information, see the Security page.

Signing Secret

The Signing Secret is a security feature that enables you to verify the authenticity of incoming requests from ClearFeed. When you enable this setting, ClearFeed will sign each outgoing request with a unique signature using this secret. To ensure the integrity of the data received, you can verify the signature on your end.

How to use the Signing Secret:

Every request ClearFeed sends to your endpoint contains a signature. This signature has to be validated to ensure the request actually originated from ClearFeed.

Important Note: Keep your Signing Secret confidential and do not share it with unauthorized parties.

Validating Requests

To validate that a request originated from ClearFeed, follow these steps:

1. Grab your webhook secret from the Developer Settings page.

2. Extract the verb, URL, body and timestamp from the request. The timestamp to use here is the X-CF-Timestamp header. Concatenate all of these and hash them using the webhook secret obtained above.

3. Compare the resulting signature with the signature in the request.

Here's how it can be done using JavaScript:

function verifySignature(signingSecret, verb, url, body, timestamp, signature) {
  if (Math.floor(Date.now() / 1000) - timestamp > 60 * 5) {
    // The request timestamp is more than five minutes from local time.
    // It could be a replay attack, so let's ignore it.
    return;
  }
  const message = verb + url + body + timestamp;
  const hmac = crypto.createHmac('sha256', signingSecret);
  const calculatedSignature = hmac.update(message).digest('hex');
  return signature === calculatedSignature;
}

Events API Subscription

The Events API Subscription allows you to subscribe to the ClearFeed Request Creation event. Whenever the event occurs, ClearFeed will send a POST request to the URL you specify in this setting.

Subscribing to Events

1. Go to the Developer Settings page and find the "Events API Subscription" section.

2. Enter the URL of your server or application endpoint where you want to receive the events.

3. Click the "Save" button to save your subscription preferences.

Endpoint Requirements

Before saving the Events API Subscription endpoint, please ensure the following:

1. The URL must start with https.

2. The endpoint should respond with an HTTP status code 200 to confirm the successful receipt of a test ping. Returning anything other than 200 that will not allow you to save the endpoint.

Receiving Events

When an event occurs, ClearFeed will send a POST request to the specified URL with relevant event data. The payload of the POST request will contain information about the event, allowing you to take appropriate actions on your end.

Event Headers

The following headers are sent with every request:

{
  'X-CF-Signature': signature,
  'X-CF-Timestamp': timestamp,
  'X-CF-Retry-Count': number
}

The X-CF-Timestamp header indicates the UNIX timestamp at which the event occurred in ClearFeed. The X-CF-Retry-Count header indicates the number of times ClearFeed tried to deliver the event. The value ranges from 0 to 3.

Supported Events

Request Created

{
  "id": "f86719a97f3c9e4b4d03c47b5a95b01d",
  "type": "request",
  "sub_type": "created",
  "source": "slack_event",
  "request": {
    "id": 352,
    "state": "Pending",
    "title": "Urgent: Payment Issue",
    "channel_id": "CHJ34K2L0PE",
    "collection_id": 11,
    "priority": "urgent",
    "request_thread": {
      "channel_id": "CHJ34K2L0PE",
      "team_id": "T0987ABCD23",
      "thread_ts": "1793901532.775815"
    },
    "triage_thread": {
      "channel_id": "CHJ34K2L0PE",
      "team_id": "T0987ABCD23",
      "thread_ts": "1793901540.119234"
    }
  },
  "event": {
    "type": "message",
    "visibility": "public",
    "source": "support_channel",
    "request_channel": {
      "channel_id": "CHJ34K2L0PE",
      "team_id": "T0987ABCD23",
      "text": "Hey team, we have an urgent issue. Can someone assist?",
      "ts": "1793901532.775815",
      "user_id": "U09XYZ456AB"
    },
    "triage_channel": {
      "channel_id": "CHJ34K2L0PE",
      "team_id": "T0987ABCD23",
      "text": "Hey team, we have an urgent issue. Can someone assist?",
      "ts": "1793901540.119234",
      "user_id": "U09XYZ456AB"
    }
  }
}

ClearFeed API

Detailed documentation of the ClearFeed API is available in the ClearFeed API Reference.