Webhooks (Strings)

Inhalte werden von Phrase Language AI maschinell aus dem Englischen übersetzt.

Verfügbar für

Team-, Business-, Enterprise-, Professional- und Software-UI/UX-Pläne

Kontaktiere Vertrieb für Fragen zur Lizenzierung.

Webhooks benachrichtigen externe Dienste wie Chat-Clients oder andere externe APIs über Ereignisse. Ein Webhook kann eine URL festlegen, wenn ein bestimmtes Ereignis eintritt.

Wichtig

Datei-Uploads lösen nur die Webhook-Ereignisse uploads:create und uploads:processing aus.

Die Webhook-Ereignisse keys:create, keys:update, translations:create und translations:update werden nicht durch Datei-Uploads oder automatisierte Importe über Folgendes ausgelöst:

Repo-Synchronisierungen (GitHub, GitLab, Bitbucket Integrationen)
CLI Push
Figma Plugin

Es gibt eine Aufbewahrungsfrist von 30 Tagen für den Webhook-Verlauf.

Webhook-Antwort

Ein Webhook-Endpunkt muss innerhalb von 5 Sekunden nach Erhalt eines Callbacks einen HTTP-Statuscode im Bereich 200–299 zurückgeben. Andere Statuscodes und Zeitüberschreitungen bei Anfragen gelten als Zustellungsfehler. Ein Webhook wird deaktiviert, wenn die Zustellung für mehr als 10 aufeinanderfolgende Ereignisse fehlschlägt. Callbacks werden nicht wiederholt.

Wird ein Callback empfangen, muss innerhalb des 5-Sekunden-Anfragezeitlimits geantwortet werden. Um zu vermeiden, dass Anwendungen versehentlich eine Zeitüberschreitung auslösen, sollte die Verarbeitung erst nach dem Versand der HTTP-Antwort erfolgen.

Integrität von Webhook-Anfragen

Jede Webhook-Anfrage enthält einen X-PhraseApp-Signature-Header, der unter Verwendung des Webhook-Verifizierungstokens als Geheimnis zusammen mit den in der Anfrage gesendeten Daten generiert wird. Der Ursprung der Anfrage wird überprüft, indem der HMAC-Digest des Anfragekörpers berechnet und mit dem Wert im X-PhraseApp-Signature-Header verglichen wird.

Beispiele:

Ruby

def verify_webhook(signatureheader)
  digest = OpenSSL::Digest::Digest.new('sha256')
  hmac = OpenSSL::HMAC.digest(digest, VERIFICATION_TOKEN, request.body)
  hmac = Base64.encode64(hmac).strip
  hmac == signatureheader
end

<?PHP

function verify_webhook($signatureheader){
  $hmac = hash_hmac('sha256', $requestBody, $verificationToken, true);
  $hmac = trim(base64_encode($hash));
  return $hmac == $signatureheader;
}

Webhook-Ereignisse

Die Struktur jedes Webhook-Payloads ist in einer Schemadatei definiert, die unter https://app.phrase.com/webhook_schemas/<event_underscored_name>.json verfügbar ist, wobei <event_underscored_name> dem Namen des Webhook-Ereignisses mit Unterstrichen entspricht.

Auf https://app.phrase.com/webhook_schemas/branches_create.json kann auf branches:create zugegriffen werden.

Ereignisname	Beschreibung
`branches:create`	Ein Branch wurde erstellt.
`branches:merge`	Ein Branch wurde zusammengeführt.
`comments:create`	Ein Kommentar zu einem Übersetzungsschlüssel wurde hinzugefügt.
`custom_metadata_values:batch_update`	Ein Wert eines benutzerdefinierten Metadatenfelds wurde in mehreren Schlüsseln aktualisiert.
`custom_metadata_values:update`	Ein Wert eines benutzerdefinierten Metadatenfelds wurde auf Schlüsselebene aktualisiert.
`jobs:complete`	Ein Job wurde als abgeschlossen markiert.
`jobs:create`	Ein Job wird erstellt.
`jobs:locale:complete`	Eine Lokalisierung eines Jobs wurde als abgeschlossen markiert.
`jobs:locale:reopened`	Eine Lokalisierung eines Jobs wurde wieder geöffnet.
`jobs:locale:review:complete`	Eine Lokalisierung eines Jobs wurde überprüft und als abgeschlossen markiert.
`jobs:locale:review:reopen`	Eine Lokalisierung eines Jobs wurde überprüft und wieder geöffnet.
`jobs:reopened`	Ein Job wurde wieder geöffnet.
`jobs:start`	Ein Job wurde gestartet.
`jobs:update`	Ein Job wird aktualisiert.
`key_links:create`	Ein untergeordneter Schlüssel ist mit einem übergeordneten Schlüssel verknüpft.
`key_links:delete`	Ein untergeordneter Schlüssel wird von einem übergeordneten Schlüssel getrennt.
`keys:batch_delete`	Mehrere Schlüssel wurden gelöscht.
`keys:create`	Ein Schlüssel wurde erstellt.
`keys:delete`	Ein Schlüssel wurde gelöscht.
`keys:tags:batch_create`	Tags wurden zu mehreren Schlüsseln hinzugefügt.
`keys:tags:create`	Tags wurden zu einem Schlüssel hinzugefügt.
`keys:update`	Ein Schlüssel wurde umbenannt oder geändert.
`locales:create`	Eine neue Sprachversion wurde in einem Projekt erstellt.
`locales:delete`	Eine Sprachversion wurde gelöscht.
`locales:update`	Eine Sprachversion wurde geändert, umbenannt oder neu konfiguriert.
`project:update`	Ein Projekt wurde geändert oder neu konfiguriert.
`releases:create`	Ein OTA-Release wurde erstellt.
`releases:delete`	Ein OTA-Release wurde gelöscht.
`screenshots:create`	Ein Screenshot wurde erstellt.
`screenshots:delete`	Ein Screenshot wurde gelöscht.
`screenshots:update`	Ein Screenshot wurde geändert oder umbenannt.
`translations:batch_delete`	Eine Liste von Übersetzungen wurde gelöscht.
`translations:batch_include`	Eine Liste von Übersetzungen wurde einbezogen.
`translations:batch_review`	Eine Liste von Übersetzungen wurde überprüft.
`translations:batch_unreview`	Eine Liste von Übersetzungen wurde nicht überprüft.
`translations:batch_unverify`	Eine Liste von Übersetzungen wurde nicht verifiziert.
`translations:batch_verify`	Eine Liste von Übersetzungen wurde verifiziert.
`translations:create`	Eine Übersetzung eines Schlüssels in einer bestimmten Sprachversion wurde hinzugefügt.
`translations:deliver`	Eine Übersetzung eines Schlüssels in einer bestimmten Sprachversion wurde von einem Sprachdienstleister geliefert.
`translations:exclude`	Eine Übersetzung eines Schlüssels in einer bestimmten Sprachversion wurde ausgeschlossen.
`translations:include`	Eine Übersetzung eines Schlüssels in einer bestimmten Sprachversion wurde einbezogen.
`translations:review`	Eine Übersetzung eines Schlüssels in einer bestimmten Sprachversion wurde überprüft.
`translations:unreview`	Eine Übersetzung eines Schlüssels in einer bestimmten Sprachversion wurde nicht überprüft.
`translations:unverify`	Eine Übersetzung eines Schlüssels in einer bestimmten Sprachversion wurde nicht verifiziert.
`translations:update`	Eine Übersetzung eines Schlüssels in einer bestimmten Sprachversion wurde bearbeitet.
`translations:verify`	Eine Übersetzung eines Schlüssels in einer bestimmten Sprachversion wurde verifiziert.
`uploads:create`	Eine Lokalisierungsdatei wurde erfolgreich verarbeitet.
`uploads:processing`	Eine Lokalisierungsdatei wird verarbeitet.

Webhook hinzufügen

Zum Hinzufügen eines Webhooks sind die folgenden Schritte auszuführen:

Auf der Seite Integrations nach unten scrollen, bis Webhooks sichtbar sind, und anschließend Configure auswählen.

Die Seite Webhooks wird geöffnet.
Add webhook auswählen.

Das Fenster Add webhook wird geöffnet.
Webhook-Details angeben.
Optional kann Include branches ausgewählt werden.
Klicke auf Speichern. Der angegebene Webhook wird der Liste auf der Seite Webhooks hinzugefügt.

Ein Webhook kann über das Menü More eines bestimmten Webhooks deaktiviert werden.

Testen eines Webhooks

Zum Testen eines Webhooks:

Auf der Seite Webhooks einen Webhook auswählen und anschließend im Menü More Send Test-Notification auswählen.

Es wird ein Hinweis angezeigt, der angibt, dass der Test erfolgreich war.

Zum Erfassen des Inhalts eines Webhooks kann ein Dienst wie RequestBin genutzt werden. RequestBin stellt eine URL bereit, die Anfragedaten zur Überprüfung sammelt.

Verwendung von Webhook-Daten

Jedes Mal, wenn ein Ereignis des angegebenen Typs eintritt, wird eine POST-Anfrage an die angegebene Callback-URL gesendet. Das POST-Payload der Anfrage ist ein JSON-kodiertes Dokument mit relevanten Daten für das Ereignis. Die Attribute event, message und sent_at werden immer enthalten sein, zusammen mit zusätzlichen für das Ereignis relevanten Attributen wie user, project und branch, von dem aus der Webhook ausgelöst wurde.

Antwort-Header

HTTP-Anfragen an die Callback-URL enthalten mehrere spezielle Header.

X-PhraseApp-Event Die Art des Ereignisses, das den Webhook ausgelöst hat.
X-PhraseApp-Signature Der HMAC-Hex-Digest der Nutzlast unter Verwendung des Hooks-Geheimnisses als Schlüssel.

Beispiel:

Content-Type: application/json
X-PhraseApp-Event: translation:create
X-PhraseApp-Signature: abc123

{
  "event": "translations:create",
  "message": "Peter hat page.help.title auf fr. übersetzt.",
  "gesendet_am": "2015-01-29T09:52:53Z"   
  "user": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe",
    "email": "joe@phrase.com",
    Position "Leitender Entwickler",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  "project": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Android Project",
    "main_format": "xml",
    "project_image_url": "http://assets.phrase.com/project.png",
    "account": "account",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  "branch": {
  "name": "branch_name"
  },
  "translation": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "content": "My translation",
    "unverified": false,
    "excluded": false,
    "plural_suffix": "",
    "key": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "home.index.headline",
      "plural": false
    },
    "locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "de",
      "code": "de-DE"
    },
    "placeholders": [
      "%{count}"
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
}