Using Turvo's self-service Public API and webhooks

Turvo Super Admin users can create and manage public API keys and configure webhook events, to facilitate integrations between Turvo and third party systems, within Turvo’s Admin console.

This article covers:

Note: Only Super Admins can create and manage public API and Webhook profiles. Users with Admin-level permissions and above can view the information available on the Configuring Public API page.

Creating users for API profiles

Before you can create an API profile, you must create an Admin-level user to associate with it. This username appears in the shipment or order timelines whenever a change is made to the entity by that specific integration. Therefore, it is important to create a special Admin user for these profiles rather than using a real person’s username.

To learn how to create a user, see How to create and manage users.

We recommend using the name of the system you are integrating with as the name of the user. For instance, if you are creating an API profile for a CRM integration, name the user “CRM Integration.”

Note: Email addresses associated with users in Turvo should be real, valid email addresses. Passwords are required for API authentications and, if needed, password generation links are sent to the email associated with the user. This means that your organization may need to create email addresses that correspond to the admin users needed for API profiles.

Accessing the Public API and Webhooks page

To create public API profiles, webhook profiles, manage your API keys, or access public API documentation:

  1. Login to your Turvo tenant, click the Profile icon at the top right of the page, and select Admin console from the drop-down menu.

Profile_icon_-_Admin_console.png

  1. Then, click the API & Webhooks card.

Updated_Admin_API_and_Webhooks.png

  1. On the Configuring Public API and Webhooks page, you can perform the actions outlined below.

API Key management features

Important note: This feature may not be available in your tenant. Contact your Turvo representative if you need help enabling the API Key management features.

Within the Public API and Webhooks page, users with Admin and Super admin permissions can easily manage features of your API keys such as naming, updating, and copying the key itself, as well as viewing last updated details, and the API call rate limit per unit time. 

Creating API keys

To generate the API key, click the +ADD NEW KEY button in the API & Webhooks page’s header.

Add_API_key.png

The screen refreshes with an automatically generated API key. The auto-generated name of the API key is the name of your tenant and a randomly generated combination of alpha-numeric characters.

4_ViewKey_2024R4.png

Editing API key names

You can choose to give your keys unique names to help easily recognize the keys being used and appropriately connect them to other systems. 

To edit the names of your API keys, click the Edit icon to the right of the API key name field.

5_RenameKey_2024R4.png

Then, enter the desired name for your key and click the check mark to save your changes. 

Rename_key_and_save.png

Refreshing and copying keys

Users also have the ability to manually refresh their key without having to reach out to Turvo support. However, it’s important to note that keys can only be updated once a week. To refresh the API key, click the circular arrow icon to the right of the key.

7_RefreshKey_2024R4.png

Additionally, if you need to copy the key for any reason, you can click the copy icon immediately to the right of the refresh icon or highlight the text with your cursor to copy the key using right-click, Ctrl+C on Windows PCs, or Cmd+C on Mac.

8_CopyKey_2024R4.png

Clicking the icon automatically copies the key to your computer’s clipboard, so you can easily paste it where it’s needed. 

Viewing Last updated details and API Call rate limit per unit time

Users can easily view the details of when the API key was last updated and the Call rate limit per unit time below the API Key.

9_CheckCallRate_2024R4.png

Protip: For information on accessing API documentation, see our How to access Turvo Public API & Webhooks documentation article.

Understanding rate limits

Your API gateway has one central rate limit, rather than user-level limits. 

  1. Make sure that your public API users are not consuming calls without consideration of the overall public API rate limit. 
    1. For example, if your organization as a whole has a 30,000 calls per 24 hours rate limit with ten public API user profiles, it’s possible for one user to consume all 30,000 calls or for all ten users to make various amounts equaling 30,000 calls in 24 hours.
    2. Note: Turvo considers a 24 hour rolling time for rate limit. Turvo maintains two levels of rate limit: a per second and a per 24 hours rolling limit. 
  2. Turvo does not support non-gateway authentication. 
  3. If you expect your public API load to increase in the future, requiring a higher rate limit, contact your Turvo representative to have your rate limit increased before you reach your tenants rate limit threshold. Doing so in advance mitigates the chances of an integration failure due to exceeded rate limits.
  4. Once you reach your rate limit threshold, Turvo rejects any further calls from that point until the rolling averages of your 24 hour limit and per second limit are within the permissible limits, or your rate limit is increased. 
    1. Rate limit increases are not done automatically by Turvo. You must contact your Turvo representative to request them.
    2. If you reach your rate limit threshold, there are two options: 
      1. Wait until your 24 hour and per second rolling rate limits are automatically lifted by the system. 
      2. Contact Turvo to increase your rate limit if you believe your future average calls per day will continue to exceed your current rate limit.

Note: Upon your request for a rate limit increase, Turvo holds the right to perform an analysis of your average calls per day and to increase the rate limit gradually once requested, rather than increasing to the requested amount immediately.

Important note: Be aware that, when testing APIs in your my-sandbox environment, your rate limits in your my-sandbox environment are less than the rate limits in your production environment. If you are unsure of your correct rate limits, contact your Turvo representative. 

AWS Document API File Size Limitations

When ingesting documents to your Turvo tenant via API, a maximum file size of 10MB per document file per call. This is a limitation imposed by our gateway provider. If you use the Turvo document API, ensure that your document files are less than 10MB to prevent file size errors.

Expiring API Gateway Keys

Users receive an email and an on-screen message when the token is set to expire. Click the GENERATE NEW API KEY to update the key.

11556_001.png

Emails are sent:

  • Four months before expiration
  • Two months before expiration
  • One month before expiration
  • Two weeks before expiration
  • One week before expiration
  • One day before expiration

The notifications panel alerts you to the emails that were not delivered. 

11556_0002.png

Public API Profile management features

Within the Public API and Webhooks page, users with Admin and Super admin permissions can create, edit, and delete API profiles.

Creating public API profiles

Turvo’s Public API provides you with the ability to integrate with Turvo through RESTful methods. Our API has predictable, resource-oriented URLs, uses HTTP response codes to indicate API errors, and all requests and responses are in JSON format.

  1. On the Configuring Public API page, make sure you are on the Public API Profile tab and click + Add public API profile.

  1. Next, fill in the information available in the Create public API profile modal:

    1. API profile name: Free form text where you can add any name you’d like for the profile.
    2. API user name: Start to type the name of the Admin-level user you previously created for this integration and select it from the drop-down.
  1. When all fields are completed, the save button will change from grey to blue and you can click SAVE to save your changes.

Editing existing public API profiles

Important Note: When updating existing public API profiles, make all changes in the Turvo UI only. 

Once the profile is created, you can click on the profile line to access the right pane info:

In the right pane, Admin users and above can view the following information:

  • API profile name: The name given to the profile during creation. To update the profile name, click into the field and type the new name.
  • API documentation: A link to Turvo’s public API documentation.
  • User name: The username (email) of the user account associated with this profile. This information is provided at the creation of the user and cannot be changed.
  • Password: This information is private and not shared. The user who manages API integrations should retain the password for any users created for API profiles. If the password is forgotten, a reset link can be sent to the account email address from the Turvo sign-in page.
  • Client name & client secret: Automatically populated through the backend authentication. This information is not editable.

Public API profiles can also be deactivated or reactivated by clicking the red DEACTIVATE or blue ACTIVATE buttons at the bottom left corner of the right pane. Deactivating a public API profile prevents that integration from continuing to push or pull data into/out of Turvo. If you no longer wish to use an integration, you would deactivate the profile.

Note: Only ten public API profiles can be active at any given time by default. If you need more than ten public API profiles, contact your Turvo representative to increase the limit.

If any information is edited, the save button changes from grey to blue. Click SAVE to save your changes.

Deleting public API profiles

To delete a public API profile:

  1. Click on the profile line to access the right pane info.
  2. Click DELETE.

image4.png

  1. Then, click YES on the pop-up window confirming that this user should no longer be able to use the public API profile.

image5.png

The public API profile you deleted is no longer be visible in the list. 

Creating Webhook profiles

Creating webhook profiles in the Admin console allows you to create profiles for specific updates that occur in Turvo, and those updates need to transfer to your integrated third-party system. These include changes relating to accounts, locations, users, contacts, shipments and orders. This makes updates more efficient, as you know exactly when a change has happened and don't need to rely on continuous or even periodic requests when changes aren't happening.

Note: There is no limit to the number of webhook profiles that can be created.

Creating Webhook profiles

To create a new webhook profile:

  1. Click the Webhooks tab on the Configuring Public API page.
  2. Select + Add Webhook profile.

  1. Complete the fields available in the Create Webhook profile modal.

Token types

  1. Configuring your webhook profile depends on the selected Token type. Your selection in this field changes the fields available in the modal. Select from Permanent token or OAuth 2.0 token. See the subsections below to learn more about each token type.
    1. Permanent token: Select Permanent token if your token is for lifelong use and doesn’t need to be changed/refreshed in order to send entity updates to your integrated third party integrations.

      1. Profile name: Give your webhook profile a name. We recommend naming the profile after the system using the webhook connectivity (for example, the CRM system name, external third party developer name, internal ERP system, etc).
      2. Notify URL: Provide the URL where Turvo sends the webhook events to.
      3. Token: Enter the permanent token key provided by the system using the webhook connectivity. 
        1. Note: For permanent token type, we only support bearer token.
    1. OAuth 2.0 token: Selecting the OAuth 2.0 token means that your token expires after a set period of time.

      1. Profile name: Enter the name of the webhook profile. We recommend naming the profile after the system using the webhook connectivity (ex: CRM system name, external 3rd party developer name, internal ERP system, etc).
      2. Notify URL: Enter the URL where Turvo sends the webhook events to.
      3. Auth URL: Provide the URL where Turvo fetches the token from, if the token expires.
      4. Token path: Enter the token path in response after calling the Auth URL (ex: access_token).
      5. Token type: The authorization token type. Turvo uses Bearer or Basic authorization token types. 
      6. Method: Enter the HTTP request method of the Auth URL (ex: POST).
      7. + Add header: Add header fields required to get the token.
      8. + Add body: Add body fields required to get the token.

Completing webhook profile creation

  1. Once the required fields are completed, choose which updates to subscribe to by checking the boxes available. Each checkbox represents an event that can be sent to your home system or third party integration:
    1. Create: The particular entity has been created in Turvo.
    2. Update: An update has been made to the entity in Turvo.
    3. Delete: The entity has been deleted/archived in Turvo.
    4. Status: The status of the entity has been updated in Turvo.
    5. Attach: Only applicable to tags - When a tag has been added to an entity in Turvo.
    6. Detach: Only applicable to tags - When a tag has been removed from an entity in Turvo.
    7. Countered: Only applicable to tender (offers) - When a counter offer has been sent.

Note: Some updates are not applicable to certain entities in Turvo and do not have a checkbox available to select.

  1. When all information is entered, click CREATE to save your profile.

When a change occurs to an entity that matches the webhook profile you’ve created, an HTTP request is sent to the address listed in the Notify URL field. The updates are sent as JSON objects and should be processed by the receiving integration according to our API and Webhook documentation.

Note: It may take a few minutes for requests to process once the webhook profile is created.

Managing existing webhook profiles

Once your webhook profile is created, you can manage them by clicking the three dots icon and selecting Edit or Activate/Deactivate from the drop-down menu.

Clicking Edit opens the Edit Webhook profile modal, where you can edit any of the existing information for the profile. Whenever complete, click SAVE to save your changes.

To deactivate or reactivate an existing profile, select Activate or Deactivate from the drop-down menu. Deactivating a webhook profile turns off the subscription to the updates selected in the profile.

Was this article helpful?

0 out of 0 found this helpful