Integrating with DocBloc

All four modes use the same API. Pick on where you want the signer to be.

• Headless — DocBloc emails the signer a link and they sign on our page. Your product has no signing UI at all. Start here: it is the least code and the least that can go wrong.
• Redirect — you send the signer to our page and we send them back to yours when they finish. Use when signing is part of a flow in your product.
• Iframe embed — our sign page inside your layout, with progress reported to your code as it happens.
• Native component — the signing surface as a React component in your app. Not available yet.

Create an application in DocBloc under DocBloc API. You get a client id, a client secret and a webhook secret. They are shown once — DocBloc stores only a hash of the client secret, so if you lose it you must rotate, which stops the old one working immediately.

On the same screen, set:

• Webhook URL — leave it empty and no events are delivered at all.
• Allowed redirect URLs — only needed for the redirect mode.
• Allowed embed origins — only needed for the embed mode.

Every call needs an access token. Tokens last 90 minutes, so cache one rather than exchanging per request — POST /auth is rate limited, because a genuine consumer exchanges rarely.

POST /auth
Content-Type: application/json

{ "clientId": "...", "clientSecret": "..." }

200 OK
{ "data": { "accessToken": "eyJ...", "expiresOn": "2026-09-21T12:34:56Z" } }

The client packages do this for you, including the caching and refresh: DocBloc.Client for .NET and @docbloc/client for server-side Node.

DocBloc posts an event on each state change: submission.created, submission.opened, submission.recipient_signed, submission.completed, submission.declined.

POST your-webhook-url
X-DocBloc-Signature: sha256=<hex>
X-DocBloc-Timestamp: 1700000000
X-DocBloc-Event: submission.completed

{ "type": "submission.completed", "submissionId": "...", "externalReference": "PO-4411",
  "metadata": {}, "recipientIndex": null, "status": "Completed", "timestamp": "..." }

Three rules, all of which matter:

• Verify before you deserialise. The signature is HMAC-SHA256 over {timestamp}.{raw body}. A round trip through a JSON parser and back will not verify — you need the raw bytes.
• Check the timestamp. It is inside the signed material, so checking it against a tolerance is what stops a captured delivery being replayed later.
• Be idempotent. DocBloc retries a failed delivery with backoff, so the same event can arrive twice. Do not advance a record twice for one event.

Answer quickly and do slow work behind it, or DocBloc will retry a delivery that actually succeeded.

Pass an Idempotency-Key header when creating a submission. A retried call with the same key returns the original submission instead of creating a second document and emailing the signer twice.