GET,
puoi passare un webhook_url e Samsa farà un POST di un evento firmato a esso
nel momento in cui il job raggiunge uno stato terminale.
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.
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.

