Skip to main content
skill CX Codex

documenso-webhooks-events — Claude Code skill: webhook guide

documenso-webhooks-events configures Documenso webhook endpoints and event handlers. Useful when tracking document signing status and automating downstream actions.

MIT 1 installs ★ 2,935 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jeremylongshore/tons-of-skills-marketplace --skill documenso-webhooks-events -a claude-code
Open on GitHub

What documenso-webhooks-events does

The skill provides implementation patterns for Documenso document lifecycle callbacks. It covers events such as document.created, document.signed, document.completed, and document.rejected. Sample handlers are provided for both Express in TypeScript and Flask in Python.

Event handling relies on immediate HTTP 200 acknowledgments before asynchronous execution begins. To prevent duplicate execution, it creates an idempotency key using the event type, document ID, and update timestamp. Local endpoint verification uses ngrok alongside synthetic curl payloads.

Webhooks in Documenso require a Teams plan or higher. The platform does not use HMAC signatures. It sends a raw shared secret in the X-Documenso-Secret header, which requires constant-time string comparison to avoid timing vulnerabilities.

What it helps with

  • set up Documenso webhook routes in Express or Flask
  • verify the X-Documenso-Secret header securely
  • handle document lifecycle events like completion or rejection
  • test webhook delivery locally using ngrok and curl

Example prompts for the agent

  • Set up an Express webhook endpoint for Documenso events
  • How do I verify the X-Documenso-Secret header in Python?
  • Write an idempotent handler for document.completed events

How to install documenso-webhooks-events

1Skills CLI (Vercel)

npx skills add jeremylongshore/tons-of-skills-marketplace --skill documenso-webhooks-events -a claude-code

2Manually: put the files in place

~/.claude/skills/documenso-webhooks-events/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/documenso-webhooks-events/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about documenso-webhooks-events

How do I install documenso-webhooks-events in Claude Code?

Run npx skills add jeremylongshore/tons-of-skills-marketplace --skill documenso-webhooks-events -a claude-code.

What plans support webhooks in Documenso?

Webhook functionality requires a Documenso Teams plan or higher. You also need an HTTPS endpoint and completed documenso-install-auth credentials.

Does Documenso use HMAC signatures for webhooks?

No, Documenso sends a plain shared secret in the X-Documenso-Secret header. Applications must compare it against the configured secret, preferably using constant-time string comparison.

Source text

SKILL.md · MIT
---
name: documenso-webhooks-events
description: 'Implement Documenso webhook configuration and event handling.

  Use when setting up webhook endpoints, handling document events,

  or implementing real-time notifications for document signing.

  Trigger with phrases like "documenso webhook", "documenso events",

  "document completed webhook", "signing notification".

  '
allowed-tools: Read, Write, Edit, Bash(curl:*), Bash(ngrok:*)
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- documenso
- webhooks
compatibility: Designed for Claude Code
---
# Documenso Webhooks & Events

## Output

- A verified signed, idempotent webhook/event path with redacted observability and recovery ownership.
- A receipt that records correlation ID, environment, event type, lifecycle result, and safe retry decision.

## Examples

Validate the callback signature before parsing the event, deduplicate with an opaque event ID, acknowledge within the documented timeout, and log only state/result metadata. Test in development using a synthetic document; retry transient errors with bounded backoff and quarantine terminal failures without replaying signing actions blindly.

## Overview

Configure and handle Documenso webhooks for real-time document lifecycle notifications. Webhooks require a Teams plan or higher. The webhook secret is sent via the `X-Documenso-Secret` header (not HMAC-signed -- it is a shared secret comparison).

## Prerequisites

- Documenso team account (webhooks require teams)
- HTTPS endpoint for webhook reception
- Completed `documenso-install-auth` setup

## Supported Events

| Event | Trigger | Use Case |
|-------|---------|----------|
| `document.created` | New document created | Audit logging |
| `document.sent` | Document sent for signing | Start SLA timers |
| `document.opened` | Recipient opens the document | Track engagement |
| `document.signed` | One recipient completes signing | Progress tracking |
| `document.completed` | All recipients have signed | Trigger downstream workflows |
| `document.rejected` | Recipient rejects | Alert sender, escalate |
| `document.cancelled` | Sender cancels document | Cleanup, notify recipients |

## Instructions

### Step 1: Create Webhook via Dashboard

1. Log into Documenso, navigate to **Team Settings > Webhooks**.
2. Click **Create Webhook**.
3. Enter your **HTTPS endpoint URL**.
4. Select the events you want to receive.
5. (Optional) Enter a **webhook secret** -- this value will be sent as-is in the `X-Documenso-Secret` header on every request.
6. Save.

### Step 2: Webhook Handler (Express)

```typescript
// src/webhooks/documenso.ts
import express from "express";

const router = express.Router();
const WEBHOOK_SECRET = process.env.DOCUMENSO_WEBHOOK_SECRET!;

// Middleware: verify the shared secret
function verifySecret(req: express.Request, res: express.Response, next: express.NextFunction) {
  const secret = req.headers["x-documenso-secret"];
  if (!secret || secret !== WEBHOOK_SECRET) {
    console.warn("Webhook rejected: invalid secret");
    return res.status(401).json({ error: "Invalid webhook secret" });
  }
  next();
}

router.post("/webhooks/documenso", express.json(), verifySecret, async (req, res) => {
  const { event, payload } = req.body;
  console.log(`Received ${event} for document ${payload.id}`);

  // Acknowledge immediately -- process async
  res.status(200).json({ received: true });

  // Route to handler
  try {
    await handleEvent(event, payload);
  } catch (err) {
    console.error(`Failed to process ${event}:`, err);
  }
});

async function handleEvent(event: string, payload: any) {
  switch (event) {
    case "document.completed":
      // All recipients signed -- download final PDF, update CRM
      await onDocumentCompleted(payload);
      break;
    case "document.signed":
      // One recipient signed -- track progress
      await onRecipientSigned(payload);
      break;
    case "document.rejected":
      // Recipient rejected -- alert sender
      await onDocumentRejected(payload);
      break;
    case "document.opened":
      // Track engagement for SLA
      console.log(`Document ${payload.id} opened by recipient`);
      break;
    default:
      console.log(`Unhandled event: ${event}`);
  }
}

async function onDocumentCompleted(payload: any) {
  const { id, title, recipients } = payload;
  console.log(`Document "${title}" (${id}) completed by all ${recipients?.length} recipients`);
  // Download signed PDF, store in S3, update database, notify team
}

async function onRecipientSigned(payload: any) {
  console.log(`Recipient signed document ${payload.id}`);
  // Update progress tracker, send notification
}

async function onDocumentRejected(payload: any) {
  console.log(`Document ${payload.id} REJECTED`);
  // Alert sender, create follow-up task
}

export default router;
```

### Step 3: Verification in Python

```python
# webhooks/documenso.py
from flask import Flask, request, jsonify
import hmac

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["DOCUMENSO_WEBHOOK_SECRET"]

@app.route("/webhooks/documenso", methods=["POST"])
def handle_webhook():
    # Verify shared secret (constant-time comparison)
    secret = request.headers.get("X-Documenso-Secret", "")
    if not hmac.compare_digest(secret, WEBHOOK_SECRET):
        return jsonify({"error": "Unauthorized"}), 401

    data = request.json
    event = data["event"]
    payload = data["payload"]

    print(f"Event: {event}, Document: {payload['id']}")

    if event == "document.completed":
        # Trigger post-signing workflow
        pass
    elif event == "document.rejected":
        # Alert and escalate
        pass

    return jsonify({"received": True}), 200
```

### Step 4: Local Development with ngrok

```bash
# Start your webhook server
npm run dev  # listening on port 3000

# Expose via ngrok
ngrok http 3000

# Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
# Add as webhook URL in Documenso dashboard:
# https://abc123.ngrok.io/webhooks/documenso
```

### Step 5: Test with curl

```bash
# Simulate a webhook delivery locally
curl -X POST http://localhost:3000/webhooks/documenso \
  -H "Content-Type: application/json" \
  -H "X-Documenso-Secret: $DOCUMENSO_WEBHOOK_SECRET" \
  -d '{
    "event": "document.completed",
    "payload": {
      "id": 42,
      "title": "Service Agreement",
      "status": "COMPLETED",
      "recipients": [
        { "email": "[email protected]", "name": "Jane Doe", "role": "SIGNER" }
      ]
    }
  }'
```

### Step 6: Idempotency and Reliable Processing

```typescript
// Use a Set or database to deduplicate events
const processedEvents = new Set<string>();

async function handleEventIdempotent(event: string, payload: any) {
  const eventKey = `${event}:${payload.id}:${payload.updatedAt}`;
  if (processedEvents.has(eventKey)) {
    console.log(`Skipping duplicate: ${eventKey}`);
    return;
  }
  processedEvents.add(eventKey);
  await handleEvent(event, payload);
}
```

For production, store processed event IDs in Redis or a database table rather than in-memory.

## Webhook Payload Structure

```json
{
  "event": "document.completed",
  "payload": {
    "id": 42,
    "externalId": null,
    "userId": 1,
    "teamId": 5,
    "title": "Service Agreement",
    "status": "COMPLETED",
    "createdAt": "2026-03-22T10:00:00.000Z",
    "updatedAt": "2026-03-22T14:30:00.000Z",
    "completedAt": "2026-03-22T14:30:00.000Z",
    "recipients": [
      {
        "email": "[email protected]",
        "name": "Jane Doe",
        "role": "SIGNER",
        "signingStatus": "SIGNED"
      }
    ]
  }
}
```

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| 401 on webhook | Secret mismatch | Verify `X-Documenso-Secret` matches your stored secret |
| No events received | URL not HTTPS | Use HTTPS endpoint (ngrok for local dev) |
| Duplicate processing | Retry delivery | Implement idempotency with event key deduplication |
| Handler timeout | Slow processing | Acknowledge 200 immediately, process async via queue |
| Events stop arriving | Webhook disabled | Check webhook status in Team Settings |

## Resources

- [Documenso Webhooks](https://docs.documenso.com/developers/webhooks)
- [Webhook Verification](https://docs.documenso.com/docs/developers/webhooks/verification)
- [ngrok Documentation](https://ngrok.com/docs)

## Next Steps

For performance optimization, see `documenso-performance-tuning`.

© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace

Similar skills

All skills for Backend and APIs →

From the same set139

The whole set →
emitting-api-events emitting-api-events — a skill that builds event-driven APIs: outbound webhooks, Server-Sent Events, and message broker integration. Fits projects where mutations need to notify downstream services. CX Codex +1 1installs maintainx-webhooks-events maintainx-webhooks-events configures MaintainX webhook ingestion and work order event handlers in Express. Useful when connecting maintenance status changes to external systems. CX Codex +1 1installs lindy-webhooks-events The lindy-webhooks-events skill guides setup of Lindy AI webhook triggers and application callbacks. Use it to define event contracts, validate requests, and handle retries in a Lindy integration. CX Codex +1 1installs fireflies-webhooks-events fireflies-webhooks-events walks an agent through building a Fireflies Webhooks V2 receiver: raw-body HMAC check, event allowlisting, dedupe, and a 2xx reply fast enough for the 10-second window. CX Codex +1 1installs windsurf-webhooks-events The windsurf-webhooks-events skill guides you through building Windsurf extensions with the VS Code API and forwarding workspace events to an external service. Use it to track saves, editor changes, or terminal output. CX Codex +1 1installs twinmind-webhooks-events twinmind-webhooks-events — a skill for TwinMind meeting events: transcription completion, action item extraction, and calendar sync notifications. CX Codex +1 1installs firecrawl-webhooks-events firecrawl-webhooks-events sets up Firecrawl webhook ingestion with raw HMAC-SHA256 signature verification, deduplication, and polling fallback. CX Codex +1 1installs coderabbit-webhooks-events coderabbit-webhooks-events is a Claude Code skill for designing Git-provider event automation around CodeRabbit reviews. It checks signatures and tests replay handling. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open