contentbird Convert supports the connection of external systems via the RESTHooks API, which supports the subscription of feeds via a standardized process. In this way it is possible to be notified by the server about data changes instead of actively checking for changes. This saves a considerable amount of processing power and time on both sides, as both sides only need to react via an event-driven approach when there is really something to process.
❗ Note
Support for the RESTHooks api is currently still being tested. If you have any requests or suggestions here, please let support know.
Preparations
In order to be able to set up a subscription, you need an API key for authentication at the RESTHook API of contenbird Convert, which uniquely identifies you. The API key serves as a substitute for your actual access data, so that these do not have to be disclosed to third parties. In addition, you can revoke an API key at any time if you suspect that it has been compromised. You generate the API keys in the contentbird Convert backend in your personal profile (under "Company > Personal Profile > API Keys"). Even though you can use one API key for multiple RESTHook-enabled services, you should take advantage of the opportunity and at least create an individual API key for each service. This allows for simplified management in case you want to revoke/delete an API key. Each API key can optionally be assigned a name. However, you can also identify the corresponding API key based on the prefix shown in the overview:
If you need a new API key, please press "create new api key". A new API key will be generated immediately and displayed in the following dialog:
You can set the name for this key now (or later).
Important:
Please transfer the Api key immediately (e.g. to the clipboard), as it cannot be retrieved after leaving the dialog. The Api key is stored in the database in one-way encrypted form, just like your personal access data, and cannot be restored. If you have forgotten the Api key, simply create a new one and delete the previous one.
Endpoints
The API is accessible at https://rest.contentbird-convert.com/ and is basically stateless. Thus, no cookies are set or expected.
When calling all endpoints, the API key must be specified in the Authorization header to authorize the client. The API key must be prefixed with "Bearer " (regular expression used: /Bearer\s+(.*)$/i).
If no valid API key is found, the HTTP status code of the API call is "401 Unauthorized" with the following message part:
{
"message": "Token not found"
}Successful calls are usually acknowledged with the HTTP status code "200 OK" and contain further user information in JSON format in the message part (response body). Timestamps are encoded according to ISO8601 (e.g. 2007-08-31T16:47:22.000+00:00) and are usually in UTC time.
Testing the login
Test access to the API and the API key you are currently using.
Call: GET /v1/resthooks/auth-test.
If successful, the HTTP status code of the call will be "200 OK" and you will get back the following JSON in the message body:
{
"status": 200,
"ok": true,
"userId": 12345
}The userId corresponds to that of the contentbird Convert user whose API key was used.
Listing of available campaigns
For a simplified selection of the required campaign ID, this endpoint provides an index of all active campaigns of the company account to which the user is assigned.
Call: GET /v1/resthooks/campaigns
If successful, the following JSON is returned as an example:
[
{
"id": 123234345,
"name": "Kampagnename #1"
},
{
"id": 124938437,
"name": "Kampagnename #2"
},
{
"id": 125547824,
"name": "Kampagnename #3"
},
…
]
In case of error, the HTTP status code is 500.
Retrieving a sample data record for a campaign
To enable interactive mapping of the data structure to the target system, sample data records can be generated for a specific campaign.
Call: GET /v1/resthooks/campaign/{campaignId:[0-9]+}/sample
Url parameter:
campaignId
The id of the campaign for which data is to be transferred via the RESTHooks API.
If successful, the following JSON is returned as an example:
[
{
"id": 1710421274,
"sessionId": 2961455846,
"loopNo": 1,
"created": "2024-03-14T13:01:14.000Z",
"updated": null,
"locale": "de_AT",
"firstname": "firstname sample.required",
"lastname": "lastname sample.required",
"email": "sample.required.1710421274@contentbird.io",
"country": "nl"
}
]
In case of error, the HTTP status code is 500.
Creating a subscription
Used to create a new subscription to a campaign.
Note:
If the endpoint provided by you has limitations in terms of data volume, the number of data sets and/or a rate limit, please inform our support team so that we can store these.
We are working on making the independent configuration available to you as part of this function.
Standard limitation by us:
8 MB data volume for the payload
100,000 data records
Rate limit: max. 60 requests / 60 seconds
Call: POST /v1/resthooks/campaign/{campaignId:[0-9]+}/
Url parameter:
campaignId
The id of the campaign for which data is to be transferred via the RESTHooks API.
Post parameter:
url
Target url for the subscription to which the generated data will be transferred. Only HTTP links with SSL are supported for secure data transfer.event
The event for which this subscription is set up. In the future, there will be other events here such as an update to previously submitted records.lead.create
The subscription is set up for new leads in the database.
Each call returns a JSON object that informs about the result. In the attribute "status" the HTTP status of the call is transported. In case of success this is "200" and in the attribute "payload" the object with the data of the subscription is listed (see also "Index of active subscriptions of a campaign").
In case of an error, the status "400 Bad Request" is usually returned and the attribute "error" contains an error description.
Index of active subscriptions of a campaign
Call: GET /v1/resthooks/campaign/{campaignId:[0-9]+}/
Url parameter:
campaignId
The id of the campaign.
As a result of this call, you get a JSON which lists from in an array the existing subscriptions of the company to which the current user is assigned:
[
{
id: <int>,
url: <string>,
event: <"lead.create">,
status: <"active"|"inactive">,
created_at: <sting, datetime in ISO8601>,
updated_at: <null|sting, datetime in ISO8601>
},
..
]
id
Unique reference to the subscription.
url
Destination url for the subscription, to which the generated data is transferred. For secure data transfer, only HTTP links with SSL are supported.
event
The event for which this subscription was set up. In the future, there will be other events here such as an update to previously submitted records.
lead.create
The subscription was set up for new leads in the database.
status
Indicates the current state of the subscription:
active
The subscription is active and data is delivered to the stored endpoint.inactive
The subscription is not active and no data is delivered to the deposited endpoint. This is the case, for example, if the endpoint has been unreachable for a long time (see also "Error handling").
created_at
Time when the subscription was created, formatted according to ISO 8601 and usually in UTC time zone.
updated_at
Time when the subscription was changed, formatted according to ISO 8601 and usually in time zone UTC. If no change has been made yet, the value is NULL.
Retrieving the information of a subscription
Call: GET /v1/resthooks/campaign/{campaignId:[0-9]+}/{subscriptionId:[0-9]+}/
Url parameter:
campaignId
The id of the campaign for which data is to be transferred via the RESTHooks API.subscriptionId
The id of the subscription that is to be queried.
The return corresponds to a single object from "Index of active subscriptions of a campaign":
{
id: <int>,
url: <string>,
event: <"lead.create">,
status: <"active"|"inactive">,
created_at: <sting, datetime in ISO8601>,
updated_at: <null|sting, datetime in ISO8601>
}
Updating a subscription
Currently, there is no provision for updating an existing subscription. Therefore, a new subscription would have to be created and the existing subscription would have to be deleted.
Delete a subscription
Call: DELETE /v1/resthooks/campaign/{campaignId:[0-9]+}/{subscriptionId:[0-9]+}/
Url parameter:
campaignId
The id of the campaign for which data is to be transferred via the RESTHooks API.subscriptionId
The id of the subscription that is to be deleted.
Unless there are execution errors, only an HTTP status code 200 is expected, otherwise "500 Internal Server Error" and an error description in the body.
Error handling
If a registered RESTHook is unreachable several times in a row, the corresponding subscription is automatically deactivated (after a little over 4 hours). Thereby, starting from the first failed delivery, the interval until the next attempt is increased depending on the failed operations.
If the specified endpoint can be reached again within the 4-hour time window, the regular delivery interval is restored.
If the subscription has been deactivated, no further delivery attempt will be made and it may be necessary to set up a new RESTHook. Please contact our support team beforehand to clarify the possibility of reactivating the existing subscription.