contentbird Convert unterstützt die Anbindung von externen Systemen über die RESTHooks-API, die über einen genormten Prozess das Abonnieren von Feeds unterstützt. Auf diese Weise ist es möglich, durch den Server über Datenänderungen benachrichtigt zu werden, anstatt aktiv auf Änderungen zu prüfen. Dies spart auf beiden Seiten eine beachtliche Menge Rechenleistung und Zeit ein, da beide Seiten über einen eventgetriebenen Ansatz lediglich reagieren müssen, wenn es wirklich etwas zu bearbeiten gibt.
❗ Hinweis
Die Unterstützung für die RESTHooks-Api ist aktuell noch in der Erprobung. Sollten Sie hier Wünsche oder Anregungen haben, so teilen Sie diese bitte dem Support mit.
Vorbereitungen
Um ein Abonnement einrichten zu können, benötigen Sie für die Authentifizierung an der RESTHook-API von contenbird Convert einen API-Key, der Sie eindeutig identifiziert. Der API-Key dient als Ersatz für Ihre eigentlichen Zugangsdaten, damit diese nicht Dritten offengelegt werden müssen. Zudem können Sie einen API-Key jederzeit widerrufen, wenn Sie den Verdacht haben, dass er kompromitiert wurde. Die API-Keys generieren Sie im contentbird Convert Backend in Ihrem persönlichen Profil (unter "Unternehmen > Persönliches Profil > API-Keys"). Auch wenn Sie einen API-Key für mehrere RESTHook-fähige Dienste verwenden können, sollten Sie die Möglichkeit nutzen und zumindest für jeden Dienst einen individuellen API-Key anlegen. Dies ermöglicht eine vereinfachte Verwaltung, falls Sie einen API-Key widerrufen/löschen möchten. Jedem API-Key kann optional ein Name zugeordnet werden. Sie können den entsprechenden API-Key aber auch aufgrund des in der Übersicht ausgewiesenen Prefixes identifizieren:
Wenn Sie einen neuen API-Key benötigen, dann drücken Sie bitte auf "neuen Api-Key anlegen". Es wird umgehend ein neuer Api-Key generiert und Ihnen im folgenden Dialog angezeigt:
Sie können jetzt (oder zu einem späteren Zeitpunkt) den Namen für diesen Key festlegen.
Wichtig:
Übernehmen Sie bitte sofort den Api-Key (z.B. in die Zwischenablage), da dieser nach Verlassen des Dialoges nicht erneut abrufbar ist. Der Api-Key wird ebenso wie Ihre persönlichen Zugangsdaten einwegverschlüsselt in der Datenbank abgelegt und kann nicht wiederhergestellt werden. Wenn Sie den Api-Key vergessen haben, dann legen Sie einfach einen neuen an und löschen den bisherigen.
Endpunkte
Die API ist unter https://rest.contentbird-convert.com/ erreichbar und ist grundsätzlich stateless. Somit werden keine Cookies gesetzt oder erwartet.
Beim Aufruf aller Endpunkte muss der API-Key im Header Authorization angegeben werden, um den Client zu authorisieren. Der API-Key muss dabei mit "Bearer " geprefixt werden (genutzter regulärer Ausdruck: /Bearer\s+(.*)$/i).
Wird kein gültiger API-Key gefunden, ist der HTTP-Statuscode des API-Aufrufs "401 Unauthorized" mit folgendem Nachrichtenteil:
{
"message": "Token not found"
}
Erfolgreiche Aufrufe werden in der Regel mit dem HTTP-Statuscode "200 OK" quittiert und enthalten im Nachrichtenteil (Response body) weitere Nutzinformationen im JSON-Format. Zeitstempel werden hierbei nach ISO8601 codiert (z.B. 2007-08-31T16:47:22.000+00:00) und liegen i.d.R. in UTC-Zeit vor.
Testen der Anmeldung
Testen Sie den Zugriff auf die API und den von Ihnen aktuell benutzten API-Key.
Aufruf: GET /v1/resthooks/auth-test
Im Erfolgsfall ist der HTTP-Statuscode des Aufrufs "200 OK" und Sie erhalten folgendes JSON im Nachrichtenteil zurück:
{
"status": 200,
"ok": true,
"userId": 12345
}
Die userId entspricht dabei der des contentbird Convert-Benutzers, dessen API-Key verwendet wurde.
Auflistung verfügbarer Kampagnen
Für eine vereinfachte Auswahl der benötigten Kampagnen-ID liefert dieser Endpunkt einen Index aller aktiven Kampagnen des Unternehmensaccounts, dem der Nutzer zugeordnet ist.
Aufruf: GET /v1/resthooks/campaigns
Im Erfolgsfall wird beispielhaft folgendes JSON zurück geliefert:
[
{
"id": 123234345,
"name": "Kampagnename #1"
},
{
"id": 124938437,
"name": "Kampagnename #2"
},
{
"id": 125547824,
"name": "Kampagnename #3"
}
]
Im Fehlerfall ist der HTTP-Statuscode 500.
Abruf eines Beispieldatensatzes für eine Kampagne
Um ein interaktives Mapping der Datenstruktur zum Zielsystem zu ermöglichen, lassen sich Beispieldatensätze für eine konkrete Kampagne generieren.
Aufruf: GET /v1/resthooks/campaign/{campaignId:[0-9]+}/sample
Url-Parameter:
campaignId
Die Id der Kampagne, für die Daten über die RESTHooks-API übernommen werden sollen
Im Erfolgsfall wird beispielhaft folgendes JSON zurück geliefert:
[
{
"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"
}
]
Im Fehlerfall ist der HTTP-Statuscode 500.
Anlegen eines Abonnements
Dient der Einrichtung eines neuen Abonnements auf eine Kampagne.
Hinweis:
Wenn der durch Sie bereitgestellte Endpunkt Limitierungen bezüglich des Datenvolumens, der Datensatzanzahl und/oder ein Rate-Limit aufweist, dann teilen Sie diese bitte unserem Support mit, damit wir diese hinterlegen.
Wir arbeiten daran, Ihnen die eigenständige Konfiguration im Rahmen dieser Funktion zur Verfügung zu stellen.
Standard-Limitierung durch uns:
8 MB Datenvolumen für die Payload
100.000 Datensätze
Rate limit: max. 60 Requests / 60 Sekunden
Aufruf: POST /v1/resthooks/campaign/{campaignId:[0-9]+}/
Url-Parameter:
campaignId
Die Id der Kampagne, für die Daten über die RESTHooks-API übernommen werden sollen
Post-Parameter:
url
Ziel-Url für das Abonnement, an welche die generierten Daten übermittelt werden. Für eine sichere Datenübertragung werden nur HTTP-Links mit SSL unterstützt.event
Das Ereignis, für das dieses Abonnement eingerichtet wird. In Zukunft wird es hier noch weitere Ereignisse geben wie beispielsweise ein Update auf bereits übermittelte
Datensätze.lead.create
Das Abonnement wird für neue Leads in der Datenbank eingerichtet.
Jeder Aufruf liefert ein JSON-Object zurück, welches über das Ergebnis informiert. Im Attribut "status" wird der HTTP-Status des Aufrufs transportiert. Im Erfolgsfall ist dies "200" und im Attribut "payload" wird das Objekt mit den Daten des Abonnements aufgeführt (siehe auch "Index aktiver Abonnements einer Kampagne").
Im Fehlerfall wird i.d.R. der Status "400 Bad Request" zurückgegeben und im Attribut "error" befindet sich eine Fehlerbeschreibung.
Index aktiver Abonnements einer Kampagne
Aufruf: GET /v1/resthooks/campaign/{campaignId:[0-9]+}/
Url-Parameter:
campaignId
Die Id der Kampagne
Als Ergebnis dieses Aufrufs erhalten Sie ein JSON, welches aus in einem Array die bestehenden Abonnements des Unternehmens auflistet, dem der aktuelle Nutzer zugeordnet ist:
[
{
id: <int>,
url: <string>,
event: <"lead.create">,
status: <"active"|"inactive">,
created_at: <sting, datetime in ISO8601>,
updated_at: <null|sting, datetime in ISO8601>
},
..
]
id
Eindeutige Referenz auf das Abonement.
url
Ziel-Url für das Abonnement, an welche die generierten Daten übermittelt werden. Für eine sichere Datenübertragung werden nur HTTP-Links mit SSL unterstützt.
event
Das Ereignis, für welches dieses Abonnement eingerichtet wurde. In Zukunft wird es hier noch weitere Ereignisse geben wie beispielsweise ein Update auf bereits übermittelte
Datensätze.
lead.create
Das Abonnement wurde für neue Leads in der Datenbank eingerichtet.
status
Gibt an, in welchem Zustand das Abonnement aktuell ist:
active
Das Abonnement ist aktiv und Daten werden an den hinterlegten Endpunkt geliefertinactive
Das Abonnement ist nicht aktiv und es werden keine Daten an den hinterlegten Endpunkt geliefert. Dies ist beispielsweise der Fall, wenn der Endpunkt über längere Zeit nicht erreichbar war (siehe auch Fehlerbehandlung).
created_at
Zeitpunkt, zu dem das Abonnement eingerichtet wurde, formatiert nach ISO 8601 und in der Regel in Zeitzone UTC.
updated_at
Zeitpunkt, zu dem das Abonnement geändert wurde, formatiert nach ISO 8601 und in der Regel in Zeitzone UTC. Wenn noch keine Änderung erfolgt ist, ist der Wert NULL.
Abrufen der Informationen eines Abonnements
Aufruf: GET /v1/resthooks/campaign/{campaignId:[0-9]+}/{subscriptionId:[0-9]+}/
Url-Parameter:
campaignId
Die Id der Kampagne, für die Daten über die RESTHooks-API übernommen werden sollensubscriptionId
Die Id des Abonnements, welches abgefragt werden soll.
Die Rückgabe entspricht einem einzelnen Objekt aus "Index aktiver Abonnements einer Kampagne":
{
id: <int>,
url: <string>,
event: <"lead.create">,
status: <"active"|"inactive">,
created_at: <sting, datetime in ISO8601>,
updated_at: <null|sting, datetime in ISO8601>
}
Aktualisieren eines Abonnements
Aktuell ist die Aktualisierung eines bestehenden Abonnements nicht vorgesehen. Daher müsste ein neues Abonnement angelegt und das Bestands-Abonnement gelöscht werden.
Löschen eines Abonnements
Aufruf: DELETE /v1/resthooks/campaign/{campaignId:[0-9]+}/{subscriptionId:[0-9]+}/
Url-Parameter:
campaignId
Die Id der Kampagne, für die Daten über die RESTHooks-API übernommen werden sollensubscriptionId
Die Id des Abonnements, das gelöscht werden soll.
Sofern es keine Ausführungsfehler gibt, wird lediglich ein HTTP-Statuscode 200 erwartet, sonst "500 Internal Server Error" und eine Fehlerbeschreibung im Body.
Fehlerbehandlung
Wenn ein registrierter RESTHook mehrfach in Folge nicht erreichbar ist, wird das entsprechende Abonnements automatisch deaktiviert (nach etwas über 4 Stunden). Dabei wird ab der ersten fehlgeschlagenen Auslieferung das Intervall bis zum nächsten Versuch in Abhängigkeit der fehlgeschlagenen Vorgänge erhöht.
Wenn der angegebene Endpunkt innerhalb des 4-Stunden-Zeitfensters wieder erreicht werden kann, wird das reguläre Zustellintervall wieder hergestellt.
Sollte das Abonnement deaktiviert worden sein, erfolgt kein weiterer Auslieferungsversuch mehr und es ist gegebenenfalls notwenig, einen neuen RESTHook einzurichten. Bitte kontaktieren Sie zuvor unser Supportteam, um die Möglichkeit einer erneuten Aktivierung des bestehenden Abonnements zu klären.