Alle Kollektionen
Convert (vorher Contilla Creator)
Gewinnspiel, Leads & Double-opt-In
RESTHooks-Api
RESTHooks-Api
Maximilian Hoppe avatar
Verfasst von Maximilian Hoppe
Vor über einer Woche aktualisiert

Index

Vorbereitungen | Endpunkte | Testen der Anmeldung | Auflistung verfügbarer Kampagnen | Anlegen eines Abonnements | Index aktiver Abonnements einer Kampagne | Abrufen der Informationen eines Abonnements | Löschen eines Abonnements | Fehlerbehandlung

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

Anlegen eines Abonnements

Dient der Einrichtung eines neuen Abonnements auf eine Kampagne.

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

Url-Prameter:

  • 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-Prameter:

  • 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 geliefert

  • inactive
    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-Prameter:

  • campaignId
    Die Id der Kampagne, für die Daten über die RESTHooks-API übernommen werden sollen

  • subscriptionId
    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-Prameter:

  • campaignId
    Die Id der Kampagne, für die Daten über die RESTHooks-API übernommen werden sollen

  • subscriptionId
    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.

Dies könnte Sie auch interessieren:

Einrichtung eines Exports über Zapier

Hat dies Ihre Frage beantwortet?