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
Aggiungiwebhook_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’oggettodata ha la stessa forma che ottieni
dall’endpoint di stato GET del job.
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,.
Verificare la firma
Il tuowebhook_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.|now − webhook-timestamp| > 300 secondi.
Retry e regole di consegna
- Il successo è qualsiasi risposta
2xxrestituita entro un timeout di 10 secondi (timeout di connessione 5s). Un3xxè 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.