Skip to main content
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 nel momento in cui il job raggiunge uno stato terminale.

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 terminalicompleted 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.

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 retry6 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.