V4 Webhooks

Was ist ein Webhook?

Ein Webhook ist ein im Push-Prinzip funktionierender HTTP-Rückruf, der von Frame.io ausgelöst wird, sobald in Ihrem Konto etwas Interessantes geschieht, etwa wenn die Transkodierung einer neuen Datei abgeschlossen, ein Kommentar hinzugefügt oder ein Projekt erstellt wird.

Anstatt die API abzufragen, stellen Sie eine öffentliche HTTPS-URL bereit; von Frame.io wird in Echtzeit eine JSON-Payload an diese URL gesendet, damit Sie Folgendes durchführen können:

Weitere Informationen darüber, was ein Webhook ist und was damit gemacht wird, finden Sie unter https://docs.webhook.site/ (in englischer Sprache).

Endpunkt-Übersicht

Änderungen und Aktualisierungen in Frame V4

Abonnements für Webhook-Ereignisse

Identifizieren Sie beim Erstellen und Aktualisieren von Webhooks, an welchen Ereignissen Sie interessiert sind.Wählen Sie so wenige oder so viele aus, wie Sie möchten. Beachten Sie, dass das Erlebnis besser ist, wenn Sie weniger Ereignisse abonnieren und Ihre Webhooks mit verschiedenen Benennungseinstellungen logisch auf verschiedene Endpunkte aufteilen. Dadurch können Sie Ihre Geschäftslogik auf der empfangenden Seite modellieren, sodass in gemeinsam genutzten Funktionen weniger gefiltert und weitergeleitet wird.

Projekte

Dateien

Ordner

Kommentare

Metadaten

Sammlungen

Selbstdefinierte Felder

Freigaben

Payload von Webhook-Nachrichten

Alle Webhook-Payloads enthalten das Feld type, in dem das aufgetretene Ereignis angegeben wird, und das Objekt resource.Das Objekt resource enthält den type und die ID der Frame.io-Ressource, die mit dem Ereignis verknüpft ist.

Beispiel-Payload

1
{
2
  "account": {
3
    "id": "6f70f1bd-7e89-4a7e-b4d3-7e576585a181"
4
  },
5
  "project": {
6
    "id": "7e46e495-4444-4555-8649-bee4d391a997"
7
  },
8
  "resource": {
9
    "id": "d3075547-4e64-45f0-ad12-d075660eddd2",
10
    "type": "file"
11
  },
12
  "type": "file.ready",
13
  "user": {
14
    "id": "56556a3f-859f-4b38-b6c6-e8625b5da8a5"
15
  },
16
  "workspace": {
17
    "id": "378fcbf7-6f88-4224-8139-6a743ed940b2"
18
  }
19
}

Im obigen Beispiel eines file.created-Ereignisses wird von der resource.id die ID der neu erstellten Datei angegeben.Zusätzlich sind die Objekte workspace, project und user enthalten, die die zugehörige workspace.id, project.id und user.id enthalten.Mit diesen Werten können API-Aufrufe reduziert werden, indem eingehende Ereignisse gefiltert oder lokal zwischengespeicherte Daten abgerufen werden.

Sicherheit

Standardmäßig haben alle Webhooks einen Signaturschlüssel.Mit diesem nicht konfigurierbaren Signiergeheimnis kann verifiziert werden, dass die Anfrage von Frame.io stammt.

Die Antwort-Payload für den konfigurierten Webhook enthält das Signiergeheimnis, das für diesen Webhook spezifisch ist.Dieses Geheimnis wird nur in dieser ersten Erstellungsantwort des Webhooks bereitgestellt. Speichern Sie es daher sicher in Ihrem Geheimnisspeicher oder in Umgebungsvariablen.Damit können Sie später verifizieren, dass der Webhook direkt von unseren Servern stammt und nicht abgefangen oder manipuliert wurde.

Verifizieren von Webhook-Signaturen

Zum Schutz einer Integration vor Man-in-the-Middle- und Replay-Angriffen ist es wichtig, die Signatur der Webhook-Payload zu verifizieren.Durch die Verifizierung wird gewährleistet, dass Webhook-Payloads tatsächlich von Frame.io gesendet wurden und der Inhalt der Payload nicht während des Transports verändert wurde.

In der POST-Anfrage sind die folgenden HTTP-Header enthalten:

1
import hmac
2
import hashlib
3
4
def verify_signature(curr_time, req_time, signature, body, secret):
5
    """
6
    Verify Webhook signature
7
    :Args:
8
        curr_time (float): Current epoch time
9
        req_time (float): Request epoch time
10
        signature (str): Signature provided by the Frame.io API for the given request
11
        body (str): Webhook body from the received POST
12
        secret (str): The secret for this Webhook that you saved when you first created it
13
    """
14
    if int(curr_time) - int(req_time) < 500:
15
        message = 'v0:{}:{}'.format(req_time, body)
16
        calculated_signature = 'v0={}'.format(hmac.new(
17
            bytes(secret, 'latin-1'),
18
            msg=bytes(message, 'latin-1'),
19
            digestmod=hashlib.sha256).hexdigest())
20
        if calculated_signature == signature:
21
            return True
22
    return False

Mit dem Zeitstempel wird die Systemzeit von Frame.io-Systemen wiedergegeben und angezeigt, wann der ausgehende Webhook gesendet wurde.Damit können Replay-Angriffe verhindert werden.Wir empfehlen, zu verifizieren, dass diese Zeit innerhalb von 5 Minuten der lokalen Zeit liegt.Die Signatur ist ein HMAC-SHA-256-Hash, in dem der Signaturschlüssel verwendet wird, der bei der Ersterstellung des Webhooks bereitgestellt wird.Führen Sie diese Schritten aus, um die Signatur zu verifizieren:

Wiederholungen und Protokollierung

Webhook-Tutorial

Schritt 1: Empfangsende einrichten (zuerst durchführen, damit Sie wissen, wie Ihre URL lauten wird)

Hier verwenden wir webhook.site, mit dem Sie einfach einmalige Webhook-Empfangende erstellen können, die ohne jegliche Geschäftslogik zum Inspizieren von Payloads und zum Senden grundlegender Antworten verwendet werden können.Wenn Sie zum ersten Mal zu https://webhook.site navigieren, wird ein eindeutiger Webhook-Endpunkt für Sie erstellt, den Sie sofort kopieren und verwenden können.

Diese URL ist für Ihre Sitzung eindeutig.

Schritt 2: Ereignisse wählen, die Sie abonnieren möchten

In dieser Anleitung halten wir es einfach und richten diesen Webhook so ein, dass nur file.created-Ereignisse abonniert werden.Die JSON-Payload, die wir für die Webhook-Erstellung verwenden, lautet wie folgt.

1
{
2
    "data": {
3
        "name": "asset.created sample webhook",
4
        "events": ["file.created"],
5
        "url": "https://webhook.site/c05f2216-9558-4816-bc09-f77ee7b9de40"
6
    }
7
}

Schritt 3: Webhook-Ressource mit Postman erstellen

Führen Sie mit Postman einen API-Aufruf durch und erstellen Sie die Webhook-Ressource. Geben Sie dabei in der Payload den Endpunkt webhook.site an.

Schritt 4: Testen

Jetzt, da Sie das Webhook-Abonnement erstellt und einen Endpunkt eingerichtet haben, um Webhooks zu empfangen, sollten Sie all dies testen. Lösen Sie den ersten Webhook aus, indem Sie die entsprechende Aktion durchführen, durch die er ausgelöst würde.

Da unser Beispiel so eingerichtet ist, dass es bei file.created ausgelöst wird, werden wir ein neues Asset in ein beliebiges Projekt innerhalb desjenigen Kontos und Arbeitsbereichs hochladen, in dem der Webhook eingerichtet wurde.

Zusätzliche Ressourcen