Webhooks

Webhooks let your application receive HTTP callbacks when events occur in SimpleDocs, so you don’t need to poll the API for updates.

How it works

You register a webhook endpoint via the API.
When a subscribed event occurs, SimpleDocs sends an HTTP POST request to your URL with a JSON payload.
Your server processes the payload and responds with a 2xx status code to acknowledge receipt.

Supported events

Event	Description
`execution_complete`	Fired when a request has been fully executed (all parties have signed).

New events may be added in the future. Your webhook handler should gracefully ignore unrecognized event types.

Creating a webhook

Use the Create webhook endpoint. You’ll need a token with the write scope.

Webhook URLs must use HTTPS. HTTP URLs will be rejected.

No authentication

curl -X POST https://app.simpledocs.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration",
    "url": "https://example.com/webhooks/simpledocs"
  }'

Basic authentication

curl -X POST https://app.simpledocs.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration",
    "url": "https://example.com/webhooks/simpledocs",
    "auth_type": "basic",
    "username": "webhook_user",
    "password": "secret123"
  }'

Bearer token authentication

curl -X POST https://app.simpledocs.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration",
    "url": "https://example.com/webhooks/simpledocs",
    "auth_type": "bearer",
    "token": "your-webhook-verification-token"
  }'

Webhook payloads

When an event fires, SimpleDocs delivers a POST request to your URL with a JSON body. The exact payload structure depends on the event type.

`execution_complete` payload

{
  "event": "execution_complete",
  "legal_request": {
    "id": 42,
    "name": "Vendor Agreement — Acme Corp",
    "status": "signed",
    "description": null,
    "created_at": "2026-03-05T14:30:00Z",
    "updated_at": "2026-03-05T16:00:00Z"
  },
  "requester": {
    "id": 7,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "title": "Legal Ops"
  },
  "counterparty": {
    "id": 12,
    "name": "John Smith",
    "email": "[email protected]",
    "title": "General Counsel",
    "organization_name": "Acme Corp"
  },
  "workflow": {
    "id": 3,
    "name": "Vendor Agreement",
    "status": "published",
    "nda_type": "one_nda",
    "created_at": "2026-01-10T09:00:00Z",
    "updated_at": "2026-02-20T11:00:00Z"
  },
  "questions": [
    { "Scope of work": "Cloud infrastructure services" },
    { "Duration": 2 }
  ]
}

The questions key is only present for NDA-type workflows.

Responding to webhooks

Your endpoint must return an HTTP 2xx status code within 30 seconds to indicate successful receipt. Any other status code or a timeout is treated as a delivery failure.

Best practices

Respond quickly — Process webhook payloads asynchronously (e.g., enqueue a background job) and return 200 immediately.
Handle duplicates — In rare cases a webhook may be delivered more than once. Design your handler to be idempotent.
Ignore unknown events — As new events are added, your endpoint may receive event types you haven’t seen before. Return 200 and ignore them.

Listing your webhooks

You can verify your registered webhooks at any time:

curl https://app.simpledocs.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "data": [
    {
      "id": "42",
      "type": "webhook",
      "attributes": {
        "name": "My Integration",
        "url": "https://example.com/webhooks/simpledocs",
        "auth_type": "bearer",
        "events": ["execution_complete"]
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 1,
    "total_count": 1
  }
}

Deleting a webhook

When you no longer want to receive events at an endpoint, delete its registration with the Delete webhook endpoint. You’ll need a token with the write scope.

curl -X DELETE https://app.simpledocs.com/api/v1/webhooks/42 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

A successful deletion returns 204 No Content with an empty body. Deleting an unknown webhook ID returns 404.

Deletion is permanent and cannot be undone. It removes the webhook’s event subscriptions and delivery logs. To receive events again, register a new webhook.

After deletion, SimpleDocs stops sending events to the endpoint immediately — deliveries that were already queued for the webhook are discarded rather than retried.

Getting Started

Guides

How it works

Supported events

Creating a webhook

No authentication

Basic authentication

Bearer token authentication

Webhook payloads

`execution_complete` payload

Responding to webhooks

Best practices

Listing your webhooks

Deleting a webhook

​How it works

​Supported events

​Creating a webhook

​No authentication

​Basic authentication

​Bearer token authentication

​Webhook payloads

​execution_complete payload

​Responding to webhooks

​Best practices

​Listing your webhooks

​Deleting a webhook

How it works

Supported events

Creating a webhook

No authentication

Basic authentication

Bearer token authentication

Webhook payloads

`execution_complete` payload

Responding to webhooks

Best practices

Listing your webhooks

Deleting a webhook