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 users. It must be manually created.

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

3. Deletion and Regeneration: If there are concerns about security or if a token is misplaced, it can be deleted and a new one can be generated.

Create Token

Go to the Developer Settings page and click on Generate Token to create a new token.

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 & Re-generateToken

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.

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 webook 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', webhookSecret);
  const calculatedSignature = hmac.update(message).digest('hex');
  return signature === calculatedSignature;
}

Event 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

Events API Subscription

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 ClearFeed Static API is covered here.