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.
- 1Add a webhookOn the Developers page in the app, or with
POST /webhooks. Save thewhsec_…secret. It’s shown only once. - 2Check the signatureEach request has a
ReadyInk-Signatureheader. Compare it to an HMAC of the body made with your secret. - 3Reply 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.{
"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.
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.
- Read the raw request body, before any JSON parsing.
- Split the header into
tandv1. - Compute HMAC-SHA256 of
t + "." + rawBodywith yourwhsec_…secret, as hex. - Compare it to
v1with a constant-time comparison. - Reject it if
tis 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 "", 200Use 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 withPATCH /webhooks/{id}and{"status": "enabled"}. - You may get the same event twice. The event
idstays 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 withGET /documents/{id}.
Test and debug
- Send a test event: use Send test event in the app, or
POST /webhooks/{id}/test. Awebhook.testevent arrives within seconds. - See recent deliveries:
GET /webhooks/{id}/deliverieslists the last 30 days, withstatus(pending,succeeded,failed),attempts,response_statusanderror. - 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.
