Index

Preparations | Endpoints | Testing the login | Listing of available campaigns | Creating a subscription | Index of active subscriptions of a campaign | Retrieving the information of a subscription | Updating a subscription | Delete a subscription | Error handling

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.

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).

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:

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.

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:

The userId corresponds to that of the contentbird Convert user whose API key was used.

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:

In case of error, the HTTP status code is 500.

Used to create a new subscription to a campaign.

Call: POST /v1/resthooks/campaign/{campaignId:[0-9]+}/

Url prameter:

Post parameter:

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.

Call: GET /v1/resthooks/campaign/{campaignId:[0-9]+}/

Url prameter:

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

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.

status
Indicates the current state of the subscription:

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.

Call: GET /v1/resthooks/campaign/{campaignId:[0-9]+}/{subscriptionId:[0-9]+}/

Url prameter:

The return corresponds to a single object from "Index of active subscriptions of a campaign":

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.

Call: DELETE /v1/resthooks/campaign/{campaignId:[0-9]+}/{subscriptionId:[0-9]+}/

Url prameter:

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.

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.