Webhook V4

Cos’è un webhook?

Un webhook è un callback HTTP in stile push che Frame.io attiva non appena accade qualcosa di interessante nel tuo account, ad esempio quando un nuovo file completa la transcodifica, quando viene aggiunto un commento o quando viene creato un progetto.

Invece di interrogare l’API, fornisci un URL HTTPS pubblico; Frame.io invia un payload JSON a quell’URL in tempo reale così puoi:

Per ulteriori informazioni su cosa sia un webhook e cosa faccia, consulta https://docs.webhook.site/.

Panoramica degli endpoint

Cambiamenti e aggiornamenti in Frame V4

Sottoscrizioni agli eventi webhook

Durante la creazione e l’aggiornamento dei webhook devi identificare gli eventi che ti interessano. Scegli quanti ne desideri. Tieni presente che l’esperienza è migliore se sottoscrivi meno eventi, suddividendo logicamente i tuoi webhook con diversi schemi di denominazione e diversi endpoint in modo da poter modellare la logica di business sul lato ricevente per eseguire meno operazioni di filtro e instradamento nelle funzioni condivise.

Progetti

File

Cartelle

Commenti

Metadati

Raccolte

Campi personalizzati

Condivisioni

Payload del messaggio webhook

Tutti i payload dei webhook contengono un campo type, che indica l’evento che si è verificato, nonché un oggetto resource. L’oggetto resource contiene il type e l’ID della risorsa Frame.io correlata all’evento.

Payload di esempio

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
}

Nell’esempio precedente di un evento file.created, il resource.id indica l’ID del file appena creato. Inoltre, sono inclusi gli oggetti workspace, project e user, che contengono i relativi workspace.id, project.id e user.id. Questi valori possono essere utilizzati per ridurre le chiamate API filtrando gli eventi in arrivo o cercando i dati memorizzati in cache localmente.

Sicurezza

Per impostazione predefinita, tutti i webhook hanno una chiave di firma. Questo secret di firma non configurabile può essere utilizzato per verificare che la richiesta provenga da Frame.io.

Il payload di risposta per il webhook che hai configurato include il secret di firma specifico per questo webhook. Questo secret viene fornito solo in questa risposta iniziale di creazione del webhook, quindi conservalo in un luogo sicuro nell’archivio dei secret o nelle variabili d’ambiente. Utilizzalo in seguito per verificare che il webhook provenga direttamente dai nostri server e non sia stato intercettato o manipolato in alcun modo.

Verifica delle firme dei webhook

Per proteggere un’integrazione da attacchi man-in-the-middle e replay, è essenziale verificare la firma del payload del webhook. La verifica garantisce che i payload dei webhook siano stati effettivamente inviati da Frame.io e che il contenuto del payload non sia stato modificato durante il trasporto.

Nella richiesta POST sono incluse le seguenti intestazioni HTTP:

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

La marca temporale è l’ora dei sistemi Frame.io quando viene inviato il webhook in uscita. Può essere utilizzata per prevenire attacchi di tipo replay. Si consiglia di verificare che questo orario rientri nei 5 minuti dall’orario locale. La firma è un hash HMAC SHA256 che utilizza la chiave di firma fornita quando il webhook viene creato per la prima volta. Segui questi passaggi per verificare la firma:

Nuovi tentativi e registrazione

Esercitazione sui webhook

Passaggio 1: configura l’endpoint ricevente (da fare per primo in modo da conoscere quale sarà l’URL)

Qui stiamo usando webhook.site che consente di creare facilmente un ricevitore del webhook monouso da utilizzare per ispezionare i payload, inviando risposte di base senza alcuna logica di business. Quando vai per la prima volta in https://webhook.site, viene creato un endpoint di webhook unico che puoi copiare immediatamente per l’uso.

Questo URL è unico per la sessione.

Passaggio 2: scegli l’evento (o gli eventi) da sottoscrivere

Per questa esercitazione, punteremo alla semplicità e configureremo questo webhook in modo da sottoscrivere solo eventi file.created. Il payload JSON che useremo per la creazione del webhook sarà il seguente.

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
}

Passaggio 3: crea una risorsa webhook usando Postman

Usa Postman per effettuare una chiamata API al fine di creare la risorsa webhook, fornendo l’endpoint webhook.site nel payload.

Passaggio 4: test

Dopo aver creato la sottoscrizione del webhook e configurato un endpoint per ricevere i webhook, è il momento di testarlo attivando il primo webhook ed eseguendo l’azione appropriata che lo farebbe attivare.

Poiché il nostro esempio è stato configurato per attivarsi con il trigger file.created, procederemo caricando una nuova risorsa in qualsiasi progetto all’interno dell’account e dell’area di lavoro corrispondenti in cui è stato configurato il webhook.

Risorse aggiuntive