How do I know when something finished?

Two ways, and you can use either. Polling is below and always works. A callback is usually better if you can accept an inbound request: set callbackUrl (in signature for a flow, in settings for an envelope) and we tell you instead, which matters most on a platform with a daily call budget — an envelope left open three days, polled every five minutes, is about 860 calls to learn nothing 859 times. If your receiver wants us to authenticate (a token, an API key, OAuth2 as Salesforce does), set up a callback environment and send {"env": "prod", "onSuccess": "/hooks/ok"}. To hear when a signer is replaced as well, add the optional onEvent address: it receives recipient.replaced, while onSuccess and onError keep saying only how the request ended (details).

To poll, ask GET /api/v1/flow/{flowId} (or GET /api/v1/sign/envelopes/{id} if you used the two-step path) and branch on output.status, not on the specific status string:

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" means keep asking. "succeeded" and "failed" both mean stop: between them they cover every way a flow stops changing — signed, declined, expired, cancelled — so code that checks output.status keeps working the day a new status is added, instead of looping forever on it. When you need to tell the three ways of failing apart, output.flow.status is still there.

The same two words work on an envelope: GET /api/v1/sign/envelopes/{id} answers the identical shape, with output.sign in place of output.flow. One poller, either path.

See, replay and try your webhooks

In the console, Webhooks lists every notification we sent to your system — the event, the URL, our attempts, what your server answered — and the exact body. What you can do there:

• Send again. Queues a new delivery with the same stored body: the same bytes and the same event.id, so a receiver that deduplicates recognises it and one that does not gets exactly what it was sent the first time. It goes through the ordinary schedule and retries; the original keeps its history.
• Send all abandoned again. After your server was down longer than our retries (44 hours), one press queues every abandoned event again, oldest first, each exactly as Send again would; an event already sent again is never queued twice, and at most 200 go per press.
• Send a sample event. A made-up event in the real shape, signed with your secret, sent now through the same code as a real one (https only, public addresses only, no redirects). It says event.simulated: true inside the signed body and is never retried, so you can write your handler before you have a real envelope.
• All of them are audited, and rate-limited per organisation.

Full status table: Compose and sign, in one call.