Webhooks - Parser

Register an endpoint once, and every job event is POSTed to it.

curl -sS -X POST "$API/v1/webhooks" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
     -d '{"url": "https://crm.example.com/hooks/parser", "topics": ["job.completed", "job.review_required", "job.failed"]}'

The answer holds the endpoint’s signing secret (whsec_...), shown only now. topics may also include mailbox.disconnected; an empty list receives every job event.

The event

{"id": "<event id>", "tenant_id": "acme", "topic": "job.completed", "resource_type": "job", "resource_id": "<job id>",
 "created_at": "2026-10-14T20:30:00Z",
 "payload": {"job_id": "...", "status": "completed", "result_path": "/v1/jobs/...", "review_reasons": [],
             "document_count": 3, "statements": 2, "statements_accepted": 2, "positions": 2,
             "current_withhold_pct": 21.8, "merchant_fingerprint": "mfp1:...", "related_jobs": [], "cost_usd": "0.0093"}}

The payload never carries the merchant’s transactions. Fetch result_path with your API key for the full result.

Header	Value
`X-Parser-Event-Id`	The event’s id, the same on every retry. Deduplicate on it.
`X-Parser-Topic`	The topic, e.g. `job.completed`.
`X-Parser-Signature`	`t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the endpoint secret>`

Verify the signature

Verify against the raw request body, before parsing it.

import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    signed = f"{parts['t']}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"]) and abs(time.time() - int(parts["t"])) <= tolerance

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, header, secret, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map((item) => item.split("=", 2)));
  const expected = createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= tolerance;
  return fresh && expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Delivery

Answer 2xx within 10 seconds. Anything else is retried after 30 s, 2 m, 10 m, 30 m, 1 h, 3 h, 6 h and 12 h; after that the delivery is dead. Five failures in a row pause the endpoint for 5 minutes.
Every job ends in an event. The event is written in the same transaction as the job’s final status, so it cannot be lost, and pending deliveries survive restarts.
Targets must be https and resolve to public addresses. Redirects are not followed.

Manage endpoints

Call	Does
`POST /v1/webhooks/{id}/test`	Sends a signed `ping`.
`GET /v1/webhooks/{id}/deliveries`	Every attempt, with your endpoint’s answers.
`POST /v1/webhooks/{id}/rotate-secret`	A new signing secret.
`DELETE /v1/webhooks/{id}`	Removes the endpoint.