> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchboard.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Document signing webhooks

> Configure Documenso to deliver real-time signing events to Launchboard — set the webhook URL, shared secret, and which events to subscribe to.

Launchboard integrates with [Documenso](https://documenso.com/) as its e-signature provider. When signers interact with documents sent through Launchboard's Dataroom, Documenso delivers webhook events to Launchboard automatically. Launchboard processes these events to keep document status in sync — downloading signed PDFs, computing seal hashes, and creating immutable version history on completion.

You do not need to build a webhook receiver yourself. The webhook endpoint is built into Launchboard. What you do need to configure is the URL and a shared secret inside your Documenso account so that Documenso knows where and how to send events.

***

## Webhook endpoint

Configure the following URL in your Documenso account as the webhook destination:

```
POST https://app.launchboard.xyz/api/webhooks/documenso
```

***

## Authentication

Documenso signs each webhook request with a shared secret sent in the `X-Documenso-Secret` header. Launchboard verifies this header to ensure events come from your Documenso account and not an unauthorized source.

To configure authentication:

1. Choose a strong, random secret string.
2. Set it as the webhook secret in your Documenso account's webhook configuration.
3. Contact Launchboard support to configure the matching secret on your account, or set it via **Settings → Integrations** if that option is available on your plan.

<Warning>
  The secret configured in Documenso must match the secret registered with Launchboard. Any mismatch causes Launchboard to reject the webhook with a `401` response.
</Warning>

***

## Events to subscribe to

In your Documenso webhook configuration, subscribe to at least these events:

| Documenso event      | When it fires                                          |
| -------------------- | ------------------------------------------------------ |
| `document.sent`      | Document has been sent to all recipients.              |
| `recipient.signed`   | An individual recipient has completed their signature. |
| `document.completed` | All recipients have signed; document is complete.      |
| `document.cancelled` | Document has been cancelled or rejected.               |

<Tip>
  Also subscribe to `document.pending` if your Documenso version emits it — Launchboard handles it identically to `document.sent`.
</Tip>

***

## Event to document status mapping

Launchboard maps incoming Documenso events to internal document and session statuses as follows:

| Documenso event                           | Session status | Document status     |
| ----------------------------------------- | -------------- | ------------------- |
| `document.sent`, `document.pending`       | `pending`      | `PENDING_SIGNATURE` |
| `recipient.signed` (partial completion)   | `partial`      | `PARTIALLY_SIGNED`  |
| `document.completed`                      | `completed`    | `SIGNED`            |
| `document.cancelled`, `document.rejected` | `cancelled`    | `REVIEWED`          |

Processing is **idempotent and forward-only** — receiving a `document.sent` event after a `document.completed` event will not roll back the document's status.

***

## What happens on `document.completed`

When Launchboard receives a `document.completed` event, it performs the following steps automatically:

1. Downloads the signed PDF from Documenso and stores it securely in the Dataroom.
2. Computes a **seal hash** of the signed PDF for integrity verification.
3. Creates a new immutable document version linked to the signature session.
4. Marks the document status as `SIGNED`.

The original source version of the document is preserved intact — the signed PDF is added as a new version in the document's version history, not as a replacement.

***

## Missed webhooks and reconciliation

If a webhook is missed or delayed (for example, due to a network outage or a Documenso delivery failure), Launchboard provides two ways to catch up:

* **Manual sync** — Open the document in the Dataroom Inspector and click **Sync now**. Launchboard fetches the current document state directly from Documenso and updates local status accordingly.
* **Automatic reconciliation** — A scheduled reconciliation job runs periodically to check for signature sessions that appear stale and re-sync them from Documenso.

Both paths are idempotent — running them on an already-synced document is safe.

***

## Cancellation semantics

When Launchboard processes a `document.cancelled` or `document.rejected` event:

* Launchboard attempts a best-effort remote cancel on the Documenso envelope.
* Regardless of whether the remote cancel succeeds, local state transitions to `cancelled` and the document status rolls back to `REVIEWED`.
* This ensures your Launchboard dataroom always has a consistent, deterministic view even if the Documenso API is temporarily unreachable.

***

## Error codes

Launchboard returns the following HTTP status codes from the webhook endpoint:

| Status | Meaning                                                                         |
| ------ | ------------------------------------------------------------------------------- |
| `200`  | Event processed successfully.                                                   |
| `401`  | `X-Documenso-Secret` header is missing or does not match the configured secret. |
| `400`  | Event payload could not be parsed.                                              |
| `500`  | An unexpected error occurred while processing the event. Documenso will retry.  |