Webhooks Overview

Webhooks let your application receive real-time HTTP notifications when events occur in inSigner — like a document being signed or completed. Instead of polling the API, inSigner sends a POST request to your server.

How it works

1. You register a webhook URL and select which events to receive.
2. When an event occurs, inSigner sends a POST request to your URL with event data.
3. Your server processes the event and responds with a 2xx status code.
4. If delivery fails, inSigner retries automatically.

Creating a webhook via API

POST /api/v1/webhooks

Required scope: webhooks.create

Request body

Field	Type	Required	Description
url	string	✅	Webhook endpoint URL (HTTPS required in production)
events	string[]	✅	Array of event types to subscribe to (1–50)
description	string	—	Human-readable description (max 500 chars)

curl

curl -X POST https://app.insigner.co/api/v1/webhooks \
  -H "Authorization: Bearer isk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourapp.com/webhooks/insigner",
    "events": ["document.completed", "document.declined", "signer.completed"],
    "description": "Production webhook for document events"
  }'

JavaScript

const res = await fetch('https://app.insigner.co/api/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer isk_YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://api.yourapp.com/webhooks/insigner',
    events: ['document.completed', 'document.declined', 'signer.completed'],
    description: 'Production webhook for document events'
  })
});
const { data } = await res.json();
// IMPORTANT: Save data.secret — it's only shown once!
console.log('Signing secret:', data.secret);

Python

res = requests.post(
    "https://app.insigner.co/api/v1/webhooks",
    headers={"Authorization": "Bearer isk_YOUR_API_KEY"},
    json={
        "url": "https://api.yourapp.com/webhooks/insigner",
        "events": ["document.completed", "document.declined", "signer.completed"],
        "description": "Production webhook for document events"
    }
)
data = res.json()["data"]
# IMPORTANT: Save data["secret"] — it's only shown once!
print("Signing secret:", data["secret"])

Response 201 Created

{
  "data": {
    "id": "wh_abc123",
    "url": "https://api.yourapp.com/webhooks/insigner",
    "events": "[\"document.completed\",\"document.declined\",\"signer.completed\"]",
    "status": "active",
    "description": "Production webhook for document events",
    "secret": "a1b2c3d4e5f6...64_char_hex_string",
    "createdAt": "2026-05-28T12:00:00.000Z"
  }
}

Caution

The secret field is only returned at creation time. Save it immediately — you’ll need it to verify webhook signatures.

Limits

• Maximum 10 webhooks per organization
• Maximum 50 events per webhook
• Only HTTPS URLs in production
• 10-second timeout per delivery

Managing webhooks

List webhooks

GET /api/v1/webhooks

Required scope: webhooks.read

Get webhook details

GET /api/v1/webhooks/{id}

Returns webhook details (secret is never included after creation).

Update a webhook

PATCH /api/v1/webhooks/{id}

Required scope: webhooks.update

Field	Type	Description
url	string	New endpoint URL
events	string[]	New event subscriptions
status	string	"active" or "inactive"
description	string | null	Updated description

Tip

Setting status to "active" resets the failure counter — useful after fixing a broken endpoint.

Delete a webhook

DELETE /api/v1/webhooks/{id}

Required scope: webhooks.delete

Response: 204 No Content

Webhook payload format

All webhook deliveries use the same envelope format:

{
  "id": "a1b2c3d4e5f6...",
  "event": "document.completed",
  "api_version": "2026-05-28",
  "created_at": "2026-05-28T14:30:00.000Z",
  "data": {
    // Event-specific data
  }
}

Field	Description
id	Unique delivery ID
event	Event type
api_version	API version for payload compatibility
created_at	When the event was generated
data	Event-specific payload

Request headers

Every webhook delivery includes these headers:

Header	Description	Example
Content-Type	Always JSON	application/json
User-Agent	Identifies inSigner	inSigner-Webhooks/1.0
X-InSigner-Event	Event type	document.completed
X-InSigner-Signature	HMAC signature	sha256=abc123...
X-InSigner-Delivery-Id	Unique delivery ID	a1b2c3d4...
X-InSigner-Timestamp	Unix timestamp	1716912600