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:
- Creating users for API profiles
- Accessing the Public API and Webhooks page
- Managing your API Key
- Creating public API profiles
- Editing existing public API profiles
- Creating webhooks profiles
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 that will be associated with it. This username will appear 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, 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.
Then, click the API & Webhooks card.
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 create an API key for your tenant, click the + Add api key button.
The screen refreshes with an automatically generated API key. The auto-generated name of the API key will be the name of your tenant and a randomly generated combination of alpha-numeric characters.
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.
Then, enter the desired name for your key and click the check mark to save your changes.
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.
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.
Clicking the icon will automatically copy 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.
Protip: For information on accessing API documentation, see our How to access Turvo Public API & Webhooks documentation article.
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.
Step 1:
On the Configuring Public API page, make sure you’re on the Public API Profile tab and click + Add public API profile.
Step 2:
Next, fill in the information available in the Create public API profile modal:
- API profile name: Free form text where you can add any name you’d like for the profile.
- 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.
Final Step:
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
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 will prevent 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 will change from grey to blue and you will click SAVE to save your changes.
Deleting public API profiles
Step 1:
To delete a public API profile, click on the profile line to access the right pane info. Then click DELETE.
Step 2:
Then click YES on the pop-up window confirming that this user will no longer be able to use the public API profile.
The public API profile you deleted will 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.
Step 1:
To create a new webhook profile, click the Webhooks tab on the Configuring Public API page and then select + Add Webhook profile.
Step 2:
Complete the fields available in the Create Webhook profile modal. The selected Token type will change the fields available in the modal:
Permanent token
Permanent token should be selected 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.
- Profile name: Give your webhook profile a name. 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).
- Notify URL: Provide the URL where Turvo will send the webhook events to.
- Token: Enter the permanent token key provided by the system using the webhook connectivity.
- Note: For permanent token type, we only support bearer token.
OAuth 2.0 token
OAuth 2.0 token should be selected when your token will expire after a certain time.
- 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).
- Notify URL: Enter the URL where Turvo will send the webhook events to.
- Auth URL: Provide the URL where Turvo will fetch the token from, if the token expires.
- Token path: Enter the token path in response after calling the Auth URL (ex: access_token).
- Token type: The authorization token type. Turvo uses Bearer or Basic authorization token types.
- Method: Enter the HTTP request method of the Auth URL (ex: POST).
- + Add header: Add header fields required to get the token.
- + Add body: Add body fields required to get the token.
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.
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.
Step 3:
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:
- Create: The particular entity has been created in Turvo.
- Update: An update has been made to the entity in Turvo.
- Delete: The entity has been deleted/archived in Turvo.
- Status: The status of the entity has been updated in Turvo.
- Attach: Only applicable to tags - When a tag has been added to an entity in Turvo.
- Detach: Only applicable to tags - When a tag has been removed from an entity in Turvo.
- 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 will not have a checkbox available to select.
Final Step:
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 will be sent to the Notify URL provided in Step 2. 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 will prompt 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 will turn off the subscription to the updates selected in the profile.
<%= heading %>