Skip to main content
Below are a list of the HTTP endpoints expected in an integration application. Required
  • GET /: returns app information
  • POST /validate: performs validation of the account
  • POST /api/v1/synchronizer/config: returns synchronizer configuration
  • POST /api/v1/synchronizer/schema: returns synchronizer schema
  • POST /api/v1/synchronizer/data: returns data
Optional
  • GET /logo: returns an image/svg+xml representation of the application’s logo
  • POST /api/v1/synchronizer/datalist: returns possible options for filter fields
  • POST /api/v1/synchronizer/filter/validate: performs filter fields validation
  • POST /api/v1/synchronizer/resource: returns files those behind security wall
  • POST /api/v1/synchronizer/webhooks: setting up webhook
  • POST /api/v1/synchronizer/webhooks/pre-process: verify and process incoming event
  • POST /api/v1/synchronizer/webhooks/transform: convert event payload into data that can be handled by Fibery

​
GET /

GET ”/” endpoint is the main one which returns information about the app. You can find response structure in App configuration. Response example: 
{
  "version": "1.0", // string representing the version of your app
  "name": "My Super Application", // title of the app
  "description": "All your base are belong to us!", // long description
  "authentication": [], // list of possible account authentication approaches
  "sources": [], // empty array
  "responsibleFor": { // app responsibility
    "dataSynchronization": true // indicates that app is responsible for data synchronization
  }
}
Authentication Information The authentication object includes all account schema information. It informs the Fibery front-end how to build forms for the end-user to provide required account information. This property is required, even if your application does not require authentication. At least one authentication object must be provided within array. In case when application doesn’t require authentication, the fields array must be omitted.
Read more about fields in Custom App: Fields.
Important note: if your app provides OAuth capabilities for authentication, the authentication identifiers must be oauth and oauth2 for OAuth v1 and OAuth v2, respectively.
Check Custom App: OAuth.
Only one authentication type per OAuth version is currently supported. 
{
  "authentication": [
    {
      "id": "basic", // identifier
      "name": "Basic Authentication", // user-friendly title
      "description": "Just using a username and password", // description
      "fields": [ //list of fields to be filled
        {
          "id": "username", //field identifier
          "title": "Username", //friendly name
          "description": "Your username, duh!", //description
          "type": "text", //field type (text, password, number, etc.)
          "optional": true, // is this a optional field?
        },
        /* ... */
      ]
    }
  ]
}

​
POST /validate

This endpoint performs account validation when setting up an account for the app and before any actions that uses the account. The incoming payload includes information about the account type to be validated and all fields required: If the account is valid, the app should return HTTP status 200 with a JSON object containing a friendly name for the account: Incoming body: 
{
  "id": "basic", // identifier for the account type
  "fields": { //list of field values to validate according to schema
    "username": "test_user",
    "password": "test$user!",
    /*...*/
  }
}
Success Response: 
{
  "name": "Awesome Account"
}
If the account is invalid, the app should return HTTP status 401 (Not Authorized) with a simple JSON object containing an error message: Failure Response: 
{
  "message": "Your password is incorrect!"
}
Refresh Access Token In addition this step can be used as a possibility to refresh access token. The incoming payload includes refresh and access token, also it can include expiration datetime. Response should include new access token to override expired one. Refresh Access Token Request: 
{
  "id": "oauth2",
  "fields": {
    "access_token": "xxxx",
    "refresh_token": "yyyy",
    "expire_on": "2018-01-01"
  }
}
Response sample after token refresh: 
{
  "name": "Awesome account",
  "access_token": "new-access-token",
  "expire_on": "2020-01-01"
}

​
POST /api/v1/synchronizer/config

The endpoint returns information about synchronization possibilities based on input parameters. It instructs Fibery about:
  • Available types
  • Available filters
  • Available functionalities
Request All input parameters are optional.
NameTypeDescription
accountobjectselected account’s fields
Request example: 
{
  "account": {
    "token": "user-token"
  }
}
Response Response example: 
{
  "types": [
    {"id": "bug", "name": "Bug"},
    {"id": "us", "name": "User Story"},
  ],
  "filters": [
    {
      "id": "modifiedAfter",
      "title": "Modified After",
      "optional": true,
      "type": "datebox"
    }
  ]
}
Output parameters:
NameTypeDescription
types[{id: string, name: string}]supported types list with id and display name
filtersArray of filtersit is used to help the user to exclude non-required data.
webhooks{enabled: true, type: 'ui'}Optional fields that indicates that webhook functionality is supported

​
Filter information

The filter object is used to help the user to exclude non-required data. Just like other field-like objects, the filter object is not required. If nothing is provided, users will not be able to filter out data received from the app. For more information about filters, please refer to App configuration and Fields.

​
POST /api/v1/synchronizer/schema

Integration app must provide data schema in advance so Fibery will be able to create approriate types and relations and then be able to maintain them. It should provide a schema for all requested types. Each type must contain name and id field. In additional there is a reserved field __syncAction that should be added to the schema if delta synchronization with possibility of removing items should be supported. Request Request contains:
  • types - an array of selected type ids
  • filter - currently configured filter
  • account - selected account
Request example 
{
  "types": [
    "pullrequest",
    "repository"
  ],
  "filter": {
    "owner": "fibery",
    "repositories": [
      "fibery/core",
      "fibery/ui"
    ]
  },
  "account": {
    "token": "token"
  }
}
Response Includes schema for all requested types Schema is JSON object where key is field and value if field description. Field description contains:
fielddescriptiontype
idField idstring
ignoreIs field visible in fields catalogboolean
nameField namestring
descriptionField descriptionstring
readonlyDisable modify field name and typeboolean
typeType of field”id”, “text” ,“number” , “date”, “array[text]” Learn more in Integration Schema types
relationRelation between typessee relations section
subTypeOptional Fibery sub type”url” , “integer”, “email”, “boolean”,“html”, “md”, “files”, “date-range” Learn more in Integration Schema types
Response example: 
{
  "repository": {
    "id": {
      "type": "id",
      "name": "Id"
    },
    "name": {
      "type": "text",
      "name": "Name"
    },
    "url": {
      "type": "text",
      "name": "Original URL",
      "subType": "url"
    }
  },
  "pullrequest": {
    "id": {
      "type": "id",
      "name": "Id"
    },
    "name": {
      "type": "text",
      "name": "Name"
    },
    "repositoryId": {
      "type": "text",
      "name": "Repository Id",
      "relation": {
        "cardinality": "many-to-one",
        "name": "Repository",
        "targetName": "Pull Requests",
        "targetType": "repository",
        "targetFieldId": "id"
      }
    },
    "__syncAction": {
      "type": "text",
      "name": "Sync Action"
    }
  }
}

​
Relations

relation field provides a possibility to create a relation between entities in Fibery. It contains following fields:
fielddescriptiontype
cardinalityType of relation”many-to-one”, “many-to-many”, “one-to-one”
nameName of the field on source sidestring
targetTypeId of target typestring
targetNameField name of target sidestring
targetFieldIdFind relation by value from fieldstring
Repository will have following fields (example includes only relation fields):
  • Pull Requests - Array
Pull Request will have following fields:
  • Repository Id - string - this field will be hidden from end user
  • Repository - Repository
Example: 
{
  "repository": {
    "id": {
      "type": "id",
      "name": "Id"
    },
    "name": {
      "type": "text",
      "name": "Name"
    },
    "url": {
      "type": "text",
      "name": "Original URL",
      "subType": "url"
    }
  },
  "pullrequest": {
    "id": {
      "type": "id",
      "name": "Id"
    },
    "name": {
      "type": "text",
      "name": "Name"
    },
    "repositoryId": {
      "type": "text",
      "name": "Repository Id",
      "relation": {
        "cardinality": "many-to-one",
        "name": "Repository",
        "targetName": "Pull Requests",
        "targetType": "repository",
        "targetFieldId": "id"
      }
    }
  }
}
Reserved field - __syncAction Sync action is reserved field that won’t be visible for end user. The field is used for delta synchronization when entity should be deleted.

​
POST /api/v1/synchronizer/data

Data endpoint performs actual data retrieving for the specified integration settings. Data retrieving is run by each type independently. Data synchronization supports:
  • pagination
  • delta synchronization
Request Inbound payload includes following information:
  • types - array of selected type ids
  • requestedType - currently fetching type
  • account - account on behalf of data should be fetched
  • filter - currently configured filters
  • lastSynchronizedAt - OPTIONAL field that indicated when last successful synchronization was run
  • pagination - OPTIONAL field includes pagination settings that was returned from previous data request
  • schema - current integration schema
Request example: 
{
  "requestedType": "pullrequest",
  "types": ["repository", "pullrequest"],
  "filter": {
    "owner": "fibery",
    "repositories": ["fibery/core", "fibery/ui", "fibery/apps-gallery"]
  },
  "account": {
    "token": "token"
  },
  "pagination": {
    "repositories": ["fibery/ui", "fibery/apps-gallery"]
  },
  "lastSynchronizedAt": "2020-09-30T09:08:47.074Z"
  "schema": {
    "repository": {
      "id": {
        "name": "Id",
        "type": "text"
      }
    }
  }
}

​
Response

Outboud payload includes:
  • items - REQUIRED array of fetched data rows
  • pagination - OPTIONAL parameter that includes information about pagination
  • hasNext - boolean attribute that indicates that there are more pages available
  • nextPageConfig - object that will be passed in pagination request body parameter with next page request
  • synchronizationType - OPTIONAL parameter with possible values delta or full. It indicates how data will be handled on Fibery side. If delta is set then only provided changes will be applied. Fibery will be looking for __syncAction field to identify whether row should be set or removed. If __syncAction equal REMOVE then corresponding entity will be removed. If full is set then unsynced data will be removed (if keep unsynced is unchecked).
Response example: 
{
  "items": [
    {
      "id": "PR_1231",
      "name": "Improve performance"
    },
    {
      "id": "PR_1232",
      "name": "Fix bugs"
    }
  ],
  "pagination": {
    "hasNext": true,
    "nextPageConfig": {
      "repositories": [
        "fibery/apps-gallery"
      ]
    }
  },
  "synchronizationType": "full"
}

​
Errors

If something goes wrong then integration app should respond with corresponding error HTTP status code and error message. Sample of error about sync failure: 
{
  "message": "Unable to fetch data."
}
But some errors can be fixed if try to fetch data later. In this case error body should include tryLater flag with value true. Fibery will retry this particular page later on. Sample of error about limits 
{
  "message": "Rate limits reached",
  "tryLater": true
}
OPTIONAL The /logo endpoint is used to provide a SVG representation of a connected application’s logo. This endpoint is entirely optional. Valid responses are a HTTP 200 response with a image/svg+xml content type, a HTTP 204 (No Content) response if there is no logo, or a 302 redirect to another URI containing the logo. If no logo is provided, or an error occurs, the application will be represented with our default app logo.

​
POST /api/v1/synchronizer/datalist

OPTIONAL Request The inbound payload includes:
  • types - an array of selected type ids
  • account - selected account
  • field - name of requested field
  • dependsOn - object that contains filter key-value pairs of dependant fields
Request body: 
{
  "types": [
    "pullrequest",
    "branch"
  ],
  "account": {
    "token": "token"
  },
  "field": "repository",
  "dependsOn": {
    "owner": "fibery"
  }
}
This endpoint performs retrieving datalists from filter fields that marked with datalist flag. Response The response from your API should include items that is a JSON-serialized list of name-value objects: The title in each object is what is displayed to the end-user for each value in a combobox and the value is what is stored with the filter and what will be passed with subsequent requests that utilize the user-created filter. Response sample: 
{
  "items": [
    {
      "title": "fibery/ui",
      "value": "124"
    },
    {
      "title": "fibery/core",
      "value": "125"
    }
  ]
}

​
POST /api/v1/synchronizer/filter/validate

OPTIONAL This endpoint performs filter validation. It can be useful when app doesn’t know about what filter value looks like. For example, if your app receives sql query as filter you may want to check is that query is valid. Request Request body contains:
  • types - array of selected type ids
  • account - account on behalf of data should be fetched
  • filter - currently configured filters
Request example: 
{
  "types": [
    "repository",
    "pullrequest"
  ],
  "filter": {
    "owner": "fibery",
    "repositories": [
      "fibery/core",
      "fibery/ui",
      "fibery/apps-gallery"
    ]
  },
  "account": {
    "token": "token"
  }
}
Response If the filter is valid, the app should return HTTP status 200 or 204. If the account is invalid, the app should return HTTP status 400 (Bad request) with a simple JSON object containing an error message: Error response sample: 
{
  "message": "Your filter is incorrect!"
}

​
POST /api/v1/synchronizer/resource

OPTIONAL This endpoint is used to access files that require authentication. For example, if the schema contains a files field and the files are not accessible by direct link then this route can be used to download files by specifying a url as app://resource?url=:url&value=1. As a result the route will be called with url and value params. The resource endpoint is called with all query parameters specified in app://resource url. Request Request body contains:
  • types - array of selected type ids
  • account - account on behalf of data should be fetched
  • filter - currently configured filters
  • params - list of parameters.
Response File content as a stream

​
POST /api/v1/synchronizer/webhooks

OPTIONAL The endpoint is responsible for installing, updating or reinstalling a webhook based on provided parameters. It’s the place where webhook based configuration starts. Request. It accepts following parameters:
  • types - an array of selected types ids
  • filter - currently configured filter
  • account - authenticated external account
  • webhook - OPTIONAL. If it’s null then a new webhook is going to be installed, otherwise it will contain current webhook configuration (that is returned by THIS endpoint)
{
  "types": [
    "pullrequest",
    "repository"
  ],
  "filter": {
    "owner": "fibery",
    "repositories": [
      "fibery/ui",
      "fibery/core"
    ]
  },
  "account": {
    "token": "token"
  },
  "webhook": null
}
Response: Response is a JSON object with following required fields
  • id - some random id
  • workspaceId - 3rd party workspace id linked to webhook/synchronization (e.g. slack workspace, intercom workspace, gitlab organization)
  • any other data that you want to receive on reinstall event.
{
  "id": "webhook_id",
  "workspaceId": "workspaceId",
  "events": [
    "create_repo",
    "delete_repo"
  ]
}

​
POST /api/v1/synchronizer/webhooks/pre-process

OPTIONAL The route is responsible for initial pre processing of request. Data that is received by this route is the same as 3rd party service sends without any changes (almost). It’s done to be able to calculate request signature properly. Goals of the service:
  • verify incoming request (usually it means that service should verify signature based on 3rd party system chosen algorithm, e.g. hubspot webhook verification)
  • response with data that should be sent to 3rd party caller and list of workspace ids this event will work for. HTTP status code of the response will also be forwarded to 3rd party system
Request Request payload and headers depends on 3rd party service Response Response should include following fields:
  • reply - data will be send as a response to 3rd party caller
  • workspaceIds - array of workspace ids this event can be applied on. Array can be empty
{
  "reply": {
    "challenge": "value"
  },
  "workspaceIds": [
    "team-a",
    "team-b"
  ]
}

​
POST /api/v1/synchronizer/webhooks/transform

OPTIONAL This route is responsible for converting event payload into data that can be handled by Fibery. Data is applied by delta synchronization rules. Request Request payload includes:
  • params - event headers that comes from external system.
  • payload - event body that comes from external system.
  • types - an array of selected type ids
  • filter - currently configured filter
  • account - selected account
{
  "params": {
    "x-github-id": "1234",
    "x-github-signature256": "dsadsa"
  },
  "payload": {
    "action": "create",
    "repository": {
      "id": "repo1"
    }
  },
  "types": [
    "pullrequest",
    "repository",
    "branch"
  ],
  "filter": {
    "owner": "fibery",
    "repositories": []
  },
  "account": {
    "token": "token"
  }
}
Response Response includes data object that is a map of data arrays by type id. 
{
  "data": {
    "repositories": [
      {
        "id": "repo1",
        "name": "Repo1",
        "__syncAction": "SET"
      }
    ],
    "branches": [
      {
        "id": "master",
        "name": "master",
        "repositoryId": "repo1",
        "__syncAction": "SET"
      }
    ]
  }
}