Come faccio a sapere quando qualcosa è terminato?
In due modi, e potete usare l'uno o l'altro. Il polling è descritto sotto e
funziona sempre. Una callback di solito è meglio, se potete accettare
una richiesta in ingresso: impostate callbackUrl (in signature per un flusso,
in settings per una busta) e ve lo diciamo noi;
conta soprattutto su una piattaforma con un budget giornaliero di chiamate: una
busta lasciata aperta tre giorni, interrogata ogni cinque minuti, costa circa 860 chiamate
per non sapere nulla 859 volte. Se il vostro ricevitore vuole che ci autentichiamo (un token,
una chiave API, OAuth2 come fa Salesforce), configura un
ambiente di callback e invia
{"env": "prod", "onSuccess": "/hooks/ok"}. Per sapere anche quando un firmatario
viene sostituito, aggiungete l'indirizzo facoltativo onEvent: riceve
recipient.replaced, mentre onSuccess e onError continuano
a dire soltanto come si è conclusa la richiesta
(dettagli).
Per il polling, chiedete GET /api/v1/flow/{flowId} (oppure
GET /api/v1/sign/envelopes/{id} se avete usato il percorso in due
passaggi) e decidete in base a output.status, non in base
alla specifica stringa di stato:
curl https://your-host/api/v1/flow/FLOW_ID \
-H "Authorization: Bearer YOUR_API_KEY"
{ "output": { "status": "pending",
"flow": { "status": "awaiting_signature", "closed": false },
"...": "..." } }
"status": "pending" significa: continua a chiedere.
"succeeded" e "failed" significano entrambi: fermatevi. Insieme
coprono tutti i modi in cui un flusso smette di cambiare — signed,
declined, expired, cancelled — quindi
il codice che controlla output.status continua a funzionare il giorno in cui viene
aggiunto un nuovo stato, invece di ciclare all'infinito su quello. Quando vi serve distinguere i tre
modi di fallire, output.flow.status è sempre lì.
Le stesse due parole funzionano su una busta:
GET /api/v1/sign/envelopes/{id} risponde con la stessa identica forma, con
output.sign al posto di output.flow. Un solo poller,
per entrambi i percorsi.
Vedere, reinviare e provare i vostri webhook
Nella console, Webhook elenca ogni notifica che abbiamo inviato al vostro sistema — l'evento, l'URL, i nostri tentativi, cosa ha risposto il vostro server — e il corpo esatto. Cosa potete fare lì:
- Invia di nuovo. Mette in coda una nuova consegna con lo
stesso corpo memorizzato: gli stessi byte e lo stesso
event.id, così un ricevitore che deduplica lo riconosce e uno che non lo fa riceve esattamente ciò che gli era stato inviato la prima volta. Segue la normale pianificazione e i normali tentativi; l'originale conserva la sua cronologia. Attenzione: un ricevitore che deduplica suevent.id(come dovrebbe) risponde200e non fa nulla, quindi la riga dice "consegnato" e dalla vostra parte non cambia niente. - Invia di nuovo come nuovo evento. Per provare il vostro ricevitore: lo stesso corpo con un
event.ide unoccurredAtnuovi, eevent.replayOfche nomina l'evento ripetuto, dentro il corpo firmato. La vostra deduplicazione lo lascia passare. - La loro risposta. Ogni consegna conserva cosa ha risposto il vostro server all'ultimo
tentativo: la riga di stato, qualche intestazione e i primi 500 caratteri del corpo — così si vede un
200che contiene un rifiuto. Un reinvio è una riga a sé con la sua risposta; l'originale non cambia mai. - Invia di nuovo tutti gli abbandonati. Dopo che il vostro server è rimasto giù più a lungo dei nostri tentativi (44 ore), una pressione rimette in coda ogni evento abbandonato, dal più vecchio, ciascuno esattamente come farebbe Invia di nuovo; un evento già reinviato non viene mai messo in coda due volte, e ne partono al massimo 200 per pressione.
- Invia un evento di esempio. Un evento inventato nella forma reale,
firmato con il vostro segreto, inviato subito con lo stesso codice di uno vero (solo https,
solo indirizzi pubblici, nessun redirect). Riportate
event.simulated: truedentro il corpo firmato e non viene mai ritentato, così potete scrivere il vostro handler prima di avere una busta reale. - Tutte queste azioni sono registrate nell'audit e limitate per organizzazione.
Tabella completa degli stati: Componi e firma, in una chiamata.