Statuses

Use this reference to interpret every status the application and the API show. Each status appears with its name in the API and webhooks and with the label the application shows in English. The concepts behind envelope and signer statuses are explained in Envelopes and signers.

Envelope statuses

Statuses

1. DRAFT Draft
2. SENT Sent
3. IN_PROGRESS In progress
4. COMPLETED Completed
5. CANCELLED Cancelled
6. EXPIRED Expired

Transitions

• DRAFT becomes SENT when send
• SENT becomes IN_PROGRESS when first signature
• IN_PROGRESS becomes COMPLETED when last signature
• SENT becomes COMPLETED when only signature
• DRAFT becomes CANCELLED when cancel
• SENT becomes CANCELLED when cancel
• IN_PROGRESS becomes CANCELLED when cancel
• SENT becomes EXPIRED when expiry sweep
• IN_PROGRESS becomes EXPIRED when expiry sweep

An envelope becomes EXPIRED when an expiry date was set at creation and that date arrives. After sending, cancelling is the transition a person starts; expiring and completing happen automatically.

Signer statuses

Statuses

1. PENDING Pending
2. NOTIFIED Notified
3. VIEWED Viewed
4. SIGNED Signed

Transitions

• PENDING becomes NOTIFIED when the envelope is sent and the signer gets a link
• NOTIFIED becomes VIEWED when the signer opens the link
• VIEWED becomes SIGNED when the signer submits the signature

In an envelope with sequential signing, signers in later turns stay PENDING until the previous turn finishes; then they receive their link and become NOTIFIED.

Webhook deliveries

Every event a webhook is subscribed to produces a delivery, and every delivery may have several attempts. The Settings page, Webhooks tab, shows the history with these labels.

Status	Label in the application	What it means
PENDING_RENDER	Preparing	bb-sign is preparing the delivery payload. Sending starts once it is ready.
PENDING_SEND	Sending	The payload is ready and an attempt is in flight or scheduled. The row shows "Next attempt at" with the time.
DELIVERED	Delivered	Your endpoint answered with a 2xx code. The delivery is complete.
FAILED_PERMANENT	Could not be built	bb-sign could not generate the delivery payload, so nothing was sent.
SKIPPED	Not sent	The endpoint was disabled when the event happened, so this event was not sent. It explains a gap in the events you received.
DEAD_LETTERED	Gave up	Every retry was used without a 2xx answer. The delivery is closed.

Retries follow the ladder 1m, 5m, 30m, 2h, 12h, with a random variation of 20 %. After 3 consecutive exhausted ladders, bb-sign disables the endpoint and emails the administrators. See Webhooks.

Outcome of each attempt

Outcome	Label in the application	What it means
SUCCESS	Accepted	Your endpoint answered with a 2xx code.
HTTP_ERROR	Rejected	Your endpoint answered with a code other than 2xx. Look up the delivery’s X-BBSign-Event-Id in your logs.
TRANSPORT_ERROR	Unreachable	No answer, because of a DNS error, a refused connection, an invalid TLS certificate or a timeout. Check that the URL is public and uses HTTPS.

API credentials

Credentials are listed in Settings, API credentials tab.

Status	Label in the application	What it means
Active	Active	The credential can obtain tokens and call the API.
Revoked, draining	Revoked — draining	The credential was recently revoked. It no longer obtains new tokens, and the tokens it already issued stay valid until they expire, at most 300 seconds after they were issued. The row shows “Tokens this credential already issued stop working at” with the time.
Revoked	Revoked	No token from this credential is valid. The credential stays listed for 90 days and is then removed.

Rotating a credential does not change its status: the previous secret stops working immediately and the new one is shown once. See API credentials.