API v1.0.0 · https://api.readyink.ai/v1
Guides

Webhooks

Instead of checking for changes on a schedule, let readyink.ai tell you. Add a webhook and we POST a JSON event to your URL each time a document is sent, viewed, signed, declined or completed.

  1. 1
    Add a webhookOn the Developers page in the app, or with POST /webhooks. Save the whsec_… secret. It’s shown only once.
  2. 2
    Check the signatureEach request has a ReadyInk-Signature header. Compare it to an HMAC of the body made with your secret.
  3. 3
    Reply fastReturn any 2xx within 10 seconds, then do the real work in the background.

Add a webhook

The URL must use https on a public host. Choose the events you want, or ["*"] for all of them, including types added later. A webhook gets events in the same mode as the key that made it: a ri_test_ key makes a test webhook for test documents, and a ri_live_ key makes a live one.

curl https://api.readyink.ai/v1/webhooks \
  -H "Authorization: Bearer ri_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/readyink",
    "events": ["document.completed", "recipient.signed"],
    "description": "Update our CRM"
  }'
const res = await fetch("https://api.readyink.ai/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.READYINK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/readyink",
    events: ["document.completed", "recipient.signed"],
    description: "Update our CRM",
  }),
});
const webhook = await res.json();
// Save webhook.secret now. It isn't shown again.
import os, requests

r = requests.post(
    "https://api.readyink.ai/v1/webhooks",
    headers={"Authorization": "Bearer " + os.environ["READYINK_API_KEY"]},
    json={
        "url": "https://example.com/readyink",
        "events": ["document.completed", "recipient.signed"],
        "description": "Update our CRM",
    },
)
webhook = r.json()
# Save webhook["secret"] now. It isn't shown again.
JSONResponse · 201
{
  "id": "whk_cm3x8k2p40001",
  "object": "webhook_endpoint",
  "url": "https://example.com/readyink",
  "description": "Update our CRM",
  "events": ["document.completed", "recipient.signed"],
  "test_mode": true,
  "status": "enabled",
  "disabled_reason": null,
  "failing_since": null,
  "created_at": "2026-11-11T15:04:05Z",
  "secret": "whsec_8Jx2kQ9vT4mN7pL3rW6yB1cF5hD0sA"
}

Webhooks that Zapier or Make add for your Zaps and scenarios show up in the same list, so you can see and turn off every place your events go.

Event types

type When it’s sent
document.sent The document went out to its recipients
document.viewed A recipient opened the document
recipient.verified A recipient confirmed their text code
recipient.signed A recipient finished signing
recipient.declined A recipient declined to sign
document.declined The document was declined and won’t be completed
document.completed Everyone signed. The signed PDF and certificate are ready
document.cancelled You cancelled the document
document.send_failed The document couldn’t be sent. Fix it and send again
webhook.test A test you started from the app or with POST /webhooks/{id}/test

What we send

A POST with a JSON body. data.document is the same document object the API returns, and data.recipient is included for events about one recipient.

HTTPPOST https://example.com/readyink
POST /readyink HTTP/1.1
Content-Type: application/json
ReadyInk-Signature: t=1794427800,v1=5f2c8a7d0e9b41c6a3f1d2e8b7c6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8

{
  "id": "evt_cm3x9p1q20007",
  "object": "event",
  "type": "recipient.signed",
  "created": "2026-11-11T15:12:44Z",
  "test_mode": true,
  "data": {
    "document": { "id": "doc_c9x1q8", "object": "document", "title": "Mutual NDA", "status": "out" },
    "recipient": { "id": "rcp_def456", "object": "recipient", "name": "Ana Diaz", "status": "signed" }
  }
}

The document and recipient are shortened here. You get the full objects.

Check the signature

Anyone can POST to your URL, so check that each request came from readyink.ai before you trust it. The header looks like t=<unix seconds>,v1=<hex>. v1 is an HMAC-SHA256 of "<t>.<raw body>", made with your webhook’s secret.

  1. Read the raw request body, before any JSON parsing.
  2. Split the header into t and v1.
  3. Compute HMAC-SHA256 of t + "." + rawBody with your whsec_… secret, as hex.
  4. Compare it to v1 with a constant-time comparison.
  5. Reject it if t is more than 5 minutes from now. This stops someone replaying an old request.
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.READYINK_WEBHOOK_SECRET; // whsec_...

// Use the raw body: re-serialized JSON won't match the signature.
app.post("/readyink", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("ReadyInk-Signature") || "";
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const expected = crypto.createHmac("sha256", SECRET)
    .update(`${parts.t}.${req.body}`).digest("hex");

  const ok = parts.v1 && parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  if (!ok || !fresh) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  res.sendStatus(200);          // reply first...
  queue.add(event);             // ...then do the work
});
import hmac, hashlib, json, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["READYINK_WEBHOOK_SECRET"].encode()  # whsec_...

@app.post("/readyink")
def readyink():
    raw = request.get_data()  # the raw body, before parsing
    parts = dict(p.split("=", 1) for p in request.headers.get("ReadyInk-Signature", "").split(",") if "=" in p)
    expected = hmac.new(SECRET, f"{parts.get('t')}.".encode() + raw, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(parts.get("v1", ""), expected):
        abort(400)
    if abs(time.time() - int(parts.get("t", 0))) > 300:
        abort(400)

    event = json.loads(raw)
    queue.put(event)          # do the work in the background
    return "", 200
Use the whole secret

Use the full whsec_… string as the HMAC key, including the whsec_ part.

Reply, retries and duplicates

  • Reply with any 2xx within 10 seconds. Anything else counts as a failure, including a timeout or a redirect (redirects aren’t followed).
  • Failed deliveries are retried after about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours, then daily, for 3 days.
  • A webhook that keeps failing for 3 days is turned off (disabled_reason: "failing"), and the account owner gets an email. Fix the endpoint, then turn it back on in the app or with PATCH /webhooks/{id} and {"status": "enabled"}.
  • You may get the same event twice. The event id stays the same on every retry, so save the IDs you’ve handled and skip repeats.
  • Events can arrive out of order. If order matters, compare created, or fetch the latest state with GET /documents/{id}.

Test and debug

  • Send a test event: use Send test event in the app, or POST /webhooks/{id}/test. A webhook.test event arrives within seconds.
  • See recent deliveries: GET /webhooks/{id}/deliveries lists the last 30 days, with status (pending, succeeded, failed), attempts, response_status and error.
  • Send one again now: POST /webhooks/{id}/deliveries/{did}/retry.
  • Use test mode first. Test documents are free, their emails and texts go to your test inbox, and the text code is always 000000.

Manage webhooks

Task Endpoint
List webhooks for this key’s mode GET /webhooks
Get one GET /webhooks/{id}
Change the URL, events or description PATCH /webhooks/{id}
Turn off or back on PATCH /webhooks/{id} with {"status": "disabled"} or "enabled"
Delete DELETE /webhooks/{id}

The secret is only returned when a webhook is created. To get a new one, delete the webhook and add it again. Full details are in the API reference.

Prefer to poll?

Webhooks are optional. You can still check GET /documents/{id} or GET /documents?status=completed on a schedule, as shown in Tracking and results. Many apps use both: webhooks for speed, and a daily check to catch anything missed.

Something unclear or missing? Email info@readyink.ai or use the contact page. A real person will reply.