Webhooks

Overview

Webhooks send HTTP POST requests to your endpoint whenever document events occur. This lets you build real-time integrations without polling the API.

Setting Up Webhooks

Via Dashboard

Go to Dashboard → Developer APIs → Webhooks tab
Click Create Webhook
Enter your endpoint URL (must be HTTPS)
Select the events you want to receive
Copy the Webhook Secret for signature verification

Via API

bash

curl -X POST "https://api.ziasign.com/api/v1/webhooks" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/ziasign",
    "events": ["document.sent", "document.signed", "document.completed"],
    "description": "Production webhook"
  }'

Event Types

Event	Triggered When
`document.created`	A new document is created
`document.sent`	A document is sent for signature
`document.viewed`	A signer opens the document
`document.signed`	A signer completes their signature fields
`document.completed`	All signers have signed the document
`document.declined`	A signer declines to sign
`document.voided`	The sender voids (cancels) the document
`document.expired`	The signing period expires

Webhook Payload

All webhooks share a common payload structure:

json

{
  "id": "evt_xyz789",
  "type": "document.completed",
  "createdAt": "2026-04-15T14:32:07Z",
  "data": {
    "documentId": "doc_abc123",
    "documentName": "Service Agreement.pdf",
    "status": "completed",
    "signer": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "signedAt": "2026-04-15T14:32:07Z"
    }
  }
}

Signature Verification

Every webhook request includes an X-Webhook-Signature header. Verify it to ensure the request is authentic:

typescript

import crypto from "crypto";

function verifyWebhook(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler
app.post("/webhooks/ziasign", (req, res) => {
  const signature = req.headers["x-webhook-signature"] as string;
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET!
  );

  if (!isValid) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // Process the event
  const { type, data } = req.body;
  switch (type) {
    case "document.completed":
      // Handle completed document
      break;
    case "document.declined":
      // Handle declined document
      break;
  }

  res.status(200).json({ received: true });
});

python

import hashlib
import hmac
import os

from flask import Flask, request, jsonify

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


def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)


@app.route("/webhooks/ziasign", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Webhook-Signature", "")
    if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
        return jsonify({"error": "Invalid signature"}), 401

    event = request.json
    event_type = event["type"]

    if event_type == "document.completed":
        # Handle completed document
        pass
    elif event_type == "document.declined":
        # Handle declined document
        pass

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

Retry Policy

If your endpoint returns a non-2xx status code or times out (30 seconds), ZiaSign retries with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours
6th retry	24 hours

After 6 failed attempts, the delivery is marked as failed and you receive an email notification. You can view and manually retry failed deliveries in the dashboard.

Testing Webhooks

Use the Test button in the dashboard to send a sample event to your endpoint. You can also use the sandbox environment to trigger real events without affecting production data.

Frequently asked questions

How do I verify webhook signatures?

Each webhook includes an X-Webhook-Signature header containing an HMAC-SHA256 signature. Verify it using your webhook secret to confirm the request came from ZiaSign.

What happens if my endpoint is down?

ZiaSign retries webhook deliveries with exponential backoff: 1 min, 5 min, 30 min, 2 hours, 12 hours, 24 hours. After 6 failed attempts, the delivery is marked as failed.

Can I receive webhooks for specific events only?

Yes. When creating a webhook subscription, you select which events to subscribe to. You can update the event list at any time.