Migrating from Adobe Acrobat Sign

If your team already has an Acrobat Sign integration, this guide lets you move it to bb-sign with a clear map of concepts, authentication, webhooks and endpoints. It is based on the Acrobat Sign v6 API.

Concept mapping

Acrobat Sign	bb-sign	How it carries over
Agreement	Envelope	Direct equivalent
Participant set / recipient	Signer	Each signer is one person with a signOrder. For several people, add one signer for each
Transient document	Upload to POST /api/v1/documents, then reference by id	Once attached, the document is kept with the envelope and counts toward your storage quota. Unattached uploads are deleted after 24 h
Library document / template	Documents owned by each envelope	Keep the base contract in your system and upload it when you create each envelope
Agreement state OUT_FOR_SIGNATURE	SENT, then IN_PROGRESS once the first signer signs
Agreement state SIGNED	COMPLETED	Means every signer has signed. An individual signer finishing is reported by the signer.signed event
Integration key	Client credential	See Authentication
Webhook with echo verification	Webhook with HMAC signature	See Webhooks; this is the main change
Megasign / bulk send	One envelope per recipient	Create the envelopes in a loop with POST /api/v1/envelopes
Custom workflow	Sequential or parallel signing	Set with the envelope’s sequentialSigning boolean and each signer’s signOrder
Form fields / anchors	A text marker in the PDF	The seal is placed where the PDF contains {{signerN}} (N is the signer’s order); without a marker, seals are placed on the last page. See Documents

Authentication: from integration key to client credentials

The Acrobat Sign integration key is a long-lived bearer token sent in a header. In bb-sign, an OAuth2 client-credentials pair is exchanged for a short-lived token.

	Acrobat Sign	bb-sign
Credential	An integration key	A client id and secret
Value sent	The key	A bearer token obtained with them
Lifetime	Until revoked	The token expires after 300 s; the credential lasts until revoked
Source	The Adobe admin console	Settings, tab API credentials, self-service for an org admin

curl -X POST "$BBSIGN_TOKEN_URL" \
  -d grant_type=client_credentials \
  -d client_id="$BBSIGN_CLIENT_ID" \
  -d client_secret="$BBSIGN_CLIENT_SECRET"

Both SDKs obtain the token, cache it and refresh it before it expires. If you write your own client, cache the token instead of requesting one for every call.

Revocation. Revoking stops new tokens immediately; a token already issued stays valid until it expires, at most 300 s. The settings panel shows the exact window before you confirm and lists the credential as Revoked — draining until it passes. When responding to a leak, treat the credential as active until that time has passed.

Webhooks: from echo verification to HMAC signature

This is the most important behavioural change in the migration.

Acrobat Sign verifies your endpoint by sending a clientId in the request and requiring it to be echoed in the response. Registration and verification use the same mechanism.

bb-sign signs every delivery with an HMAC-SHA256 over the raw body, in the X-BBSign-Signature header. Your endpoint verifies the signature and responds 2xx, without returning any value.

	Acrobat Sign	bb-sign
How a request is proven genuine	Echo the clientId	Verify the HMAC signature
Endpoint response	A JSON body with the id	A 2xx with no body
Value per request	The same on every request	Different on every request
Receiver’s responsibility	Respond with the echo	Verify the signature on every delivery

The last row is the key one: the integration’s security depends on your endpoint verifying the signature before it processes the event. Both SDKs include verification, and the test vectors let you validate your own implementation. The webhooks guide details the three requirements a verifier must meet.

Event contents. bb-sign delivers a compact, typed event: envelope id, title, status and, on signer.* events, the signer. For more data, query the API. This keeps payloads small and the webhook contract stable.

Endpoint mapping

Acrobat Sign	bb-sign
POST /transientDocuments	POST /api/v1/documents
POST /agreements	POST /api/v1/envelopes then POST /api/v1/envelopes/{id}/send
GET /agreements	GET /api/v1/envelopes
GET /agreements/{id}	GET /api/v1/envelopes/{id}
GET /agreements/{id}/documents	GET /api/v1/envelopes/{id}/documents
PUT /agreements/{id}/state to CANCELLED	POST /api/v1/envelopes/{id}/cancel
POST /webhooks	Settings, tab Webhooks (webhooks are managed in the UI)

Create and send are two calls. The envelope is created in DRAFT, documents are attached and then it is sent. This way, an agreement left half-built remains a draft and never reaches a signer.

The API reference describes the full surface.

Before you migrate

• Base contracts. Keep them in your system and upload them with each envelope.
• Sending to many recipients. Create one envelope per recipient with POST /api/v1/envelopes; quotas apply per organization.
• Signature placement. Add the text marker to the PDF where each seal should go.
• Signing order. Use signOrder and the sequentialSigning boolean.
• Workspaces. Every envelope belongs to a workspace, and a credential accesses the workspaces assigned to it; see Machine authentication.