Rox Register, Developers

Webhook events

Subscribe endpoints per vault (or corporate-wide) via POST /v1/webhooks. Every delivery is signed with your endpoint secret, the registration + verification snippets live in Quickstart 3. The one to alert on: verification.mismatch, someone tried to pass off an altered document.

record.anchoredThe record reached its anchored outcome: the anchor finalized on RoxChain, proof available.

record.failedThe record reached its failed outcome: anchoring failed permanently after retries.

record.revokedA revocation anchored, quorum-approved, reason hashed on-chain.

record.supersededA supersession anchored, linking old record → new.

batch.anchoredAn internal anchoring aggregate finalized. Build on the per-record record.anchored events instead.

verification.mismatchA verification failed against the anchored leaf, your tamper alarm.

verification.spikeVerification volume anomaly detected for a vault.

gas.lowGas wallet forecast dropped below the warning threshold (7 days).

gas.refilledA Rox coin deposit to the gas wallet was validated on chain and credited to the gas ledger.

key.rotation.startedAuthority key rotation began (DKG running).

key.rotation.completedRotation anchored; key history extended.

report.readyA Rox Intelligence report finished composing (PDF available).

insight.createdA new insight landed (critical ones also email + banner).

envelope.sentA signature envelope was created and sent to its signers.

envelope.signer_signedOne signer completed their signature on an envelope.

envelope.signer_declinedA signer declined; the envelope is closed as declined.

envelope.completedThe last signer signed; assembly of the final document begins.

envelope.assembledThe final signed document and completion certificate are sealed; record references are on the event.

envelope.voidedThe sender withdrew the envelope before completion.

envelope.expiredThe envelope passed its expiry before completion; no further signing is possible.

Delivery contract

•Envelope: POST JSON {id, type, created_at, data} with headers X-RR-Webhook-Id, X-RR-Webhook-Timestamp (unix seconds), X-RR-Webhook-Signature.

•Signature: v1=HMAC-SHA256(secret, ts + "." + body), lowercase hex over the exact raw body bytes.

•Retries on failure: 1m → 5m → 30m → 2h → 12h, then the delivery is marked dead and you are notified.

•An endpoint is auto-disabled after 20 consecutive failures (re-enable it from your Platform).

POST https://api.ish.example/rox/events
Content-Type: application/json
X-RR-Webhook-Id: wh_01J9AB…
X-RR-Webhook-Timestamp: 1787788800
X-RR-Webhook-Signature: v1=7f9c1a…

{
  "id": "whd_01J9CD…",
  "type": "record.anchored",
  "created_at": "2026-08-27T09:15:04.000Z",
  "data": {
    "record_id": "rec_01J8ZK…",
    "reference": "rr_ref_01J8ZKQ2M3TT9AHW5RC2E9KQ2A",
    "external_ref": "POL-2026-88123",
    "batch_id": "bat_01J8ZK…",
    "tx_signature": "3B4YxyQGKrJc8yWzSyb4ehJMd7",
    "slot": 18230441,
    "block_time": "2026-08-27T09:15:02.000Z"
  }
}

// Envelope lifecycle example: a signer completed their signature.
// Signer objects carry id, name and order_index only, never contact details.
{
  "id": "whd_01J9EF…",
  "type": "envelope.signer_signed",
  "created_at": "2026-09-09T10:02:11.000Z",
  "data": {
    "envelope_id": "env_01J9AB…",
    "name": "Master services agreement",
    "signer": { "id": "sgn_01J9CD…", "name": "Aya Hassan", "order_index": 0 },
    "signed_at": "2026-09-09T10:02:11.000Z"
  }
}

// When the last signer finishes, envelope.completed fires, followed by
// envelope.assembled once the sealed records exist:
{
  "id": "whd_01J9GH…",
  "type": "envelope.assembled",
  "created_at": "2026-09-09T10:02:14.000Z",
  "data": {
    "envelope_id": "env_01J9AB…",
    "name": "Master services agreement",
    "contract_record_id": "rec_01J9JK…",
    "contract_reference": "rr_ref_01J9JKQ2M3TT9AHW5RC2E9KQ2A",
    "certificate_record_id": "rec_01J9LM…",
    "certificate_reference": "rr_ref_01J9LMQ2M3TT9AHW5RC2E9KQ2B",
    "assembled_at": "2026-09-09T10:02:14.000Z"
  }
}

Payload changes

The event envelope carries no version field; only the signature scheme is versioned (the v1= prefix). Changes to payload fields are recorded here.

2026-09-09Added the envelope.* family (envelope.sent, envelope.signer_signed, envelope.signer_declined, envelope.completed, envelope.assembled, envelope.voided, envelope.expired) for the signature ceremony lifecycle. Signer objects carry id, name and order_index only; signer emails and phone numbers never appear in webhook payloads.

2026-08-28gas.low and gas.refilled: renamed balance_rxg to balance_rox and amount_rxg to amount_rox, matching the coin's symbol (Rox coin, ROX). Amounts are unchanged. The rename shipped before any external consumers integrated; the old names are not emitted and no aliases exist.