Basics
Webhooks
Get told when a document is ready instead of polling, and check each call is really from Rowland.
Instead of checking for progress, let Rowland tell you. Add an endpoint and its signing secret in the Rowland app, under Settings → Webhooks, and choose the events to receive.
Events
| Event | When |
|---|---|
document.ready |
A document has been read and its fields extracted. |
document.failed |
A document could not be processed. |
extraction.completed |
An extraction of your own fields has finished. |
revenue_statement.completed |
A revenue statement analysis has finished. |
mission.needs_you |
A Row Bot is waiting for an approval, an answer or a handoff. |
mission.done |
A mission has finished. |
Each one is a POST with a JSON body:
{
"object": "event",
"id": "evt_7Hk2pWq9Zr",
"type": "document.ready",
"created_at": "2026-11-20T15:05:41Z",
"data": {
"object": "document",
"id": "doc_2Hq8kLm4Vt",
"name": "whitfield-lease.pdf",
"status": "ready",
"type": "oil_gas_lease",
"needs_review": false
}
}Then fetch what you need, such as the document's fields.
Check the signature
Every call carries a Rowland-Signature header with a timestamp and a signature:
Rowland-Signature: t=1795191941,v1=5d2c0f6e…v1 is an HMAC-SHA256, keyed with your signing secret, of the timestamp, a period and the raw request body. Check it before you trust the call, and reject calls more than five minutes old:
import hashlib
import hmac
import time
def is_from_rowland(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
signed = f"{parts['t']}.".encode() + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
fresh = abs(time.time() - int(parts["t"])) < 300
return fresh and hmac.compare_digest(expected, parts.get("v1", ""))import { createHmac, timingSafeEqual } from 'node:crypto';
export function isFromRowland(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`)
.digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1 ?? '');
return fresh && a.length === b.length && timingSafeEqual(a, b);
}Delivery
- Answer fast with any
2xx, then do the work. - Failed calls are retried with backoff for up to three days.
- Each event has an
id. You may receive one more than once; skip IDs you have already handled.
