Webservices & Webhooks
Webservices
Actito's aim is to offer you a wide range of connectivity options. Consequently, we particularly want to enable the exchange of data between Actito and other systems related to your activity.
The public APIs at your disposal therefore allow you to directly interact with Actito without having to go through the interface. With the help of web services, you will be able to call data stored in Actito to retrieve. You will also be able to send data from your system towards Actito.
The Actito web services are more than a mere data exchange tool, as they enable you to activate the use of these data, but also to automatize their processing.
Indeed, the API is made of a number of routes, grouped into categories that match all the different channels and features of Actito. About everything that can be achieved in the Actito interface can be automatized through our public API.
Access to Public APIs
Actito makes access to Webservices in 4 environments: a PREPROD environment and the 3 PROD environments.
The technical documentation about these environments is online and regularly updated.
The Webservices and Webhook sections of this documentation aim at giving you a business perpective of what's possible through the Actito API.
For implementation details, developers should always refer to the API specs in the Developers Portal (above link).
Webservice account creation and authentication
The use of APIs requires authentication through an API user, different from the accounts used to access the platform.
The Actito API uses an API key-based authentication.
API keys
The license's Admin users can manage the API keys themselves (cf. Manage API users).
When creating an API user, it is important to provide the e-mail address of a person responsible for maintaining your API. Indeed, this address will be used to notify you of any impacting changes.
When setting up API calls, the API key is not directly used as an ID.
It is used to generate an access token with a limited duration (15 minutes) that must be included in all the calls.
For example, to generate a token in the TEST environment, the call would be
GET https://api-pre1.actito.com/auth/token
with the API key in the "Authorization" header.
GET Token
curl
-X GET 'https://apitest.actito.com/auth/token' \
-H 'Authorization: qhdfbvdh747R49FRHrthqXXXXXXXXX' \
-H 'Accept: application/json'
You will then get your token ("accesToken" in the response).
Reponse GET Token
{
"accessToken": "AAAAAAAAAAAAAAAAAAAAAMLheAAAAAAA0%2BuSeid%2BULvsea4JtiGRiSDSJSI%3DEUifiRBkKG5E2XzMDjRfl76ZC9Ub0wnz4XsNiRVBChTYbJcE3F",
"tokenType": "bearer",
"expiresIn": "900s",
"scope": "read write",
"jti": "ce6c1d3c-ab49-4b62-8f4c-964351ac5d58"
}
The token is used for authenticating every call during the following 15 minutes. It must be passed as a Bearer authorization in every call.
Exemple Bearer Token
curl
-X GET 'https://api-pre1.actito.com/v5/v5/entities/MyEntity/etls' \
-H "Authorization: Bearer
AAAAAAAAAAAAAAAAAAAAAMLheAAAAAAA0%2BuSeid%2BULvsea4JtiGRiSDSJSI%3DEUifiRBkKG5E2XzMDjRfl76ZC9Ub0wnz4XsNiRVBChTYbJcE3F" \
-H 'Accept: application/json'
Public API versions
In Actito we are constantly working to improve our products and expand our integration platform.
All the latest developed routes can be recognized by the /v5/ in their path.
The philosophy of the V5 is to stick closely to standard REST API usages and to improve the consistency of their behavior between resources.
It is not planned to entirely phase out the V4 or replace it altogether with V5 routes. However, changes to single V4 routes can happen and will be announced through the process documented here.
Actito Concepts available via Webservices
Each operation is grouped under a concept, which matches the Actito resource category to which the operation will be applied.
Each of these concepts may use one or more methods, according to its nature and to possible related operations.
To get to know the various concepts with which you can interact through the Actito APIs, we invite you to read the chapter dedicated to the 'Concepts Available via Webservices'.
Webhooks
Actito aims at offering you a wide range of connectivity options in your marketing approach. Consequently, we particularly want to enable the exchange of data between Actito and other systems related to your activity.
The Actito Public API enable you to automate interactions with Actito without needing to go through the interface.
Webhooks, on the other hand, give you the reverse service in comparison to the API. With them, it is required to make a GET call every time you need a piece of information. Webhooks are in fact listening to the information. By subscribing to Webhooks, the latter allow you to be directly notified when specific events occur on a profile or a custom table entry. These events will be pushed to the endpoint URL of your choice.
This section of this documentation aim at giving you a business perspective of what's possible through the Actito Integration Framework.
For implementation details, developers should always refer to the specs in the Developers Portal
Context
Affected events
Webhooks allow you to get notified about events revolving around profile tables and custom tables of the data model.
These events can be of the following nature:
- CREATE: Allows you to get notified for each profile creation or each new data record
- UPDATE: Allows you to get notified for each modification on a profile or data record. It is possible to specify exactly which field of the table must be taken into account
- DELETE: Allows you to get notified every time a profile or a record is deleted
- UPDATED_SEGMENT and UPDATED_SUBSCRIPTION: These events are specific to profile tables. They allow you to get notified for every subscription and segmentation modification
For custom tables, events must be defined in the JSON definition file of the custom table (in the "eventsToTrigger" parameter).
A CREATE event always exists by default in custom tables, but UPDATE events must be defined (notably to define updates on which fields trigger the event).
Do not hesitate to contact your account manager if you need help to set up events in your tables.
In addition to retrieving information from your tables, webhooks can also be used to get the status of your ETLs and file synchronizations, and to connect your scenarios to external systems thanks to custom actions.
Protocol
When Actito records an event that matches the definition of the Webhook subscription, the Webhook will submit the information to the URL that you specified.
To help you manage greater loads, pushes can be made "One by one" or in "Bulk" mode. Bulk mode is useful when several events are recorded at once (such as a file import), to group the events in one push. Nevertheless, webhooks are always a real-time method to get the information: even in bulk mode, if 1 event is recorded and a 2nd eventis not recorded in a matter of seconds, the webhook notification will be pushed.
Access
To receive notifications every time an event occurs in the table to which you are listening, it is necessary to create a subscription to a Webhook. A Webhook subscription must be created for each event and each table to which you are listening.
Creating and managing these subscriptions can be done through the Actito APIs. Their definition is available on the technical documentation.