Vai al contenuto principale
Ogni endpoint di generazione è asincrono. Invece di interrogare l’endpoint GET, puoi passare un webhook_url e Samsa farà un POST di un evento firmato a esso quando il job è completed o failed.

Richiedere un webhook

Aggiungi webhook_url a qualsiasi richiesta di generazione. È per richiesta — job diversi possono puntare a URL diversi.
I webhook sono una comodità, non la fonte di verità. Se ogni tentativo di consegna fallisce, il risultato del job è comunque disponibile dal suo endpoint GET. Interroga come fallback per qualsiasi cosa critica.

Eventi

I webhook si attivano solo sulle transizioni terminali — completed o failed. I job cancelled non emettono un webhook.

Payload

Il corpo della richiesta è JSON. L’oggetto data ha la stessa forma che ottieni dall’endpoint di stato GET del job.
Per un evento failed, status è "failed" e data porta un oggetto error che usa la stessa forma interna dell’envelope di errore.
Blocchi di compliance. Un evento immagine completed il cui job ha avuto alcuni output trattenuti dalla pipeline di compliance porta le images consegnabili più blocked_images (vedi Blocchi di compliance). Un job di immagine i cui output sono stati trattenuti tutti non invia alcun webhook — il suo stato GET mostra failed con error delivery_blocked_compliance: <codes>.

Header di firma

Ogni consegna porta tre header:
Lo schema è compatibile con Svix: HMAC-SHA256 su {webhook-id}.{webhook-timestamp}.{raw-body}, codificato in base64, con prefisso v1,.
Firma e verifica sui byte grezzi della richiesta esattamente come ricevuti — mai una copia ri-serializzata. La ri-serializzazione (riordinare le chiavi, cambiare gli spazi bianchi) cambia i byte e rompe la firma.

Verificare la firma

Il tuo webhook_secret per chiave vive nell’app sotto Settings → API Keys (ogni chiave ha il proprio segreto; ruotalo indipendentemente dalla chiave). Gli snippet qui sotto sono verificati rispetto a un vettore di test fisso — eseguili così come sono e restituiscono true, così puoi confermare che la tua implementazione riproduca la firma byte per byte prima di collegare un segreto reale.
Il corpo del vettore di test è una stringa di riferimento fissa, quindi i suoi byte esatti non cambiano mai e la firma rimane riproducibile — intenzionalmente non è il payload dell’evento live mostrato sopra. La verifica della firma gira sempre sui byte grezzi esatti che ricevi, qualunque sia la loro forma, quindi questo è puramente un self-test per il tuo verificatore. Allo stesso modo, webhook-id è una stringa opaca e stabile per evento — trattala come un token, non analizzarla mai.
In produzione, applica sempre anche la finestra del timestamp: rifiuta la consegna se |now − webhook-timestamp| > 300 secondi.

Retry e regole di consegna

  • Il successo è qualsiasi risposta 2xx restituita entro un timeout di 10 secondi (timeout di connessione 5s). Un 3xx è trattato come un fallimento — Samsa non segue i redirect.
  • In caso di fallimento, Samsa riprova con il tentativo iniziale più 5 retry — 6 tentativi di consegna in totale — con back-off 5s → 30s → 2m → 15m → 1h.
  • Dopo il tentativo finale la consegna viene abbandonata (e registrata). Il risultato del job resta interrogabile dal suo endpoint GET.
  • Gli endpoint devono essere HTTPS. Rispondi rapidamente (2xx) ed esegui l’elaborazione pesante in modo asincrono così non superi mai la finestra di 10 secondi.
Usa il webhook-id stabile per rendere il tuo handler idempotente. Una consegna ritentata riusa lo stesso webhook-id, così puoi ignorare in sicurezza un evento che hai già elaborato.