Skip to content

Popular

  • QuickstartDevelopers
  • AuthenticationBasics
  • WebhooksBasics
  • Upload a documentPOST /v1/read/documents
  • Get a document’s fieldsGET /v1/read/documents/{id}/fields
  • Extract your own fieldsREAD · Document Extraction
Overview menu

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:

json
{
  "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:

text
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:

python
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", ""))
javascript
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.