Payload Reference

Public webhook payload examples for launched event types.

Every webhook delivery uses the same envelope:

json

{
  "event": "<event_type>",
  "timestamp": "2026-02-11T10:30:00.000Z",
  "data": { ... }
}

Payloads include only the information needed to update your app. Business data stays private unless you included it in the submitted record.

`delta.verified`

Fired after a usage delta is recorded and verified.

json

{
  "event": "delta.verified",
  "timestamp": "2026-02-11T10:30:12.456Z",
  "data": {
    "receiptId": "0x8f3a9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f",
    "deltaIndex": null,
    "status": "verified",
    "verifiedAt": "2026-02-11T10:30:12.000Z",
    "verificationId": "0xabc123...",

    "delta": {
      "customerId": "cust_8xKj2m",
      "amount": -42.50,
      "reason": "usage_charge",
      "referenceId": "inv_20260211_001",
      "metadata": {
        "plan": "growth",
        "source": "usage_api"
      },
      "submittedAt": "2026-02-11T10:30:00.000Z"
    },

    "proof": {
      "proofHash": "0x8f3a9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f",
      "contentHash": "0x2d4e7f1a3b5c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
      "itemHashes": [
        "0x2d4e7f1a3b5c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
        "0x9f1a3c5e7b2d4f6a8c0e1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a4c6e8b0d1f"
      ],
      "previousProofHash": "0x1c7b2e4a6d8f0b3c5e7a9d1f3b5c7e9a2d4f6b8c0e2a4d6f8b1c3e5a7d9f0b"
    },

    "verification": {
      "verified": true,
      "latencyMs": 1204,
      "discrepancies": []
    },

    "period": {
      "id": "2026-02",
      "deltaCount": 1042,
      "netDelta": 0
    },

    "usage": {
      "plan": "growth",
      "periodId": "2026-02",
      "includedDeltas": 500000,
      "consumedDeltas": 1042,
      "remainingDeltas": 498958,
      "overageRate": "$0.010/delta"
    }
  }
}

Field Reference

Top-level fields

Field	Type	Description
`receiptId`	`string`	Proof root that serves as the unique receipt for this verified delta
`deltaIndex`	`integer \| null`	Global sequence number, or `null` if not yet assigned
`status`	`string`	Verification status. Always `"verified"` for this event
`verifiedAt`	`string`	ISO 8601 timestamp of when verification completed
`verificationId`	`string`	Identifier for the verification confirmation

`delta` object

Present when the original delta context is available. Contains the business data you submitted.

Field	Type	Description
`customerId`	`string \| null`	Your customer identifier
`amount`	`number \| null`	The delta amount (positive or negative)
`reason`	`string \| null`	Reason code for the delta
`referenceId`	`string \| null`	Your external reference identifier
`metadata`	`object`	Arbitrary metadata you attached to the delta
`submittedAt`	`string \| null`	ISO 8601 timestamp of when the delta was submitted

`proof` object

Field	Type	Description
`proofHash`	`string`	Proof root covering this delta
`contentHash`	`string \| null`	Fingerprint of this individual delta's content
`itemHashes`	`string[]`	All content fingerprints in the verification set
`previousProofHash`	`string \| null`	Proof fingerprint of the preceding record

`verification` object

Field	Type	Description
`verified`	`boolean`	Whether cross-verification passed
`latencyMs`	`integer`	Time from submission to verification in milliseconds (present when submittedAt is known)
`discrepancies`	`string[]`	List of any discrepancies found (empty when verified)

`period` object (conditional)

Included when period enrichment is available.

Field	Type	Description
`id`	`string`	Period identifier in `YYYY-MM` format
`deltaCount`	`integer`	Total deltas in the current period so far
`netDelta`	`number`	Net sum of all delta amounts in the period

`usage` object (conditional)

Included when plan information is available. usage.periodId is the billing period of the stored acceptance-time usage snapshot. It can differ from period.id, which is the verification-month aggregate.

Field	Type	Description
`plan`	`string`	Current plan name
`periodId`	`string`	Billing period for this usage snapshot (`YYYY-MM`)
`includedDeltas`	`integer`	Total deltas included in the plan
`consumedDeltas`	`integer`	Tamper-evident acceptance-time usage watermark for this period (`usage.periodId`)
`remainingDeltas`	`integer`	Deltas remaining before overage
`overageRate`	`string`	Cost per delta beyond the included amount (e.g., `"$0.010/delta"`)

`customer.created`

Fired after an admin or manager manually creates a customer in the dashboard.

json

{
  "event": "customer.created",
  "timestamp": "2026-05-16T22:30:12.456Z",
  "data": {
    "customerId": "cust_acme",
    "displayName": "Acme Corp",
    "source": "manual",
    "createdAt": "2026-05-16T22:30:12.000Z"
  }
}

This payload is intentionally limited to tenant-provided identity fields and timestamps. It does not include contact details, proof roots, access hints, or internal ledger references.

`delta.failed`

Fired when a usage delta reaches a failed state.

json

{
  "event": "delta.failed",
  "timestamp": "2026-02-11T10:30:15.789Z",
  "data": {
    "recordId": "rec_123",
    "customerId": "cust_123",
    "reason": "validation_failed",
    "message": "The submitted delta could not be recorded."
  }
}

`checkpoint.verified`

Fired when a period or window checkpoint is verified.

json

{
  "event": "checkpoint.verified",
  "timestamp": "2026-02-28T23:59:59.999Z",
  "data": {
    "checkpointId": "chk_2026_02_cust_123",
    "customerId": "cust_123",
    "period": "2026-02",
    "scope": {
      "startDate": "2026-02-01T00:00:00.000Z",
      "endDateExclusive": "2026-03-01T00:00:00.000Z"
    },
    "deltaCount": 9848,
    "fromIndex": "0",
    "toIndex": "9847",
    "proofHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "verifiedAt": "2026-02-28T23:59:59.000Z",
    "verificationId": "0xabc123...",
    "message": "Checkpoint verified. Include proofHash when both sides need to check the record."
  }
}

Field	Type	Description
`checkpointId`	`string`	Checkpoint identifier
`customerId`	`string`	Customer record identifier (`all` when tenant-wide)
`period`	`string`	Primary period label (`YYYY-MM`) when the checkpoint covers a full month
`scope`	`object`	Resolved scope boundaries used to build the checkpoint
`scope.startDate`	`string`	ISO timestamp for scope start
`scope.endDateExclusive`	`string`	ISO timestamp for exclusive scope end
`deltaCount`	`integer`	Number of verified deltas included in the checkpoint
`fromIndex`	`string`	Starting delta index covered by this checkpoint
`toIndex`	`string`	Ending delta index covered by this checkpoint
`proofHash`	`string`	Single proof root covering all deltas in the range
`verifiedAt`	`string`	ISO 8601 timestamp of verification
`verificationId`	`string`	Verification confirmation identifier
`message`	`string`	Guidance on how to use the proof root

`receipt.generated`

Fired when a shareable receipt is generated.

json

{
  "event": "receipt.generated",
  "timestamp": "2026-02-11T14:22:33.100Z",
  "data": {
    "receiptId": "rcpt_123",
    "customerId": "cust_123",
    "proofHash": "0xf0e1d2c3b4a5f0e1d2c3b4a5f0e1d2c3b4a5f0e1d2c3b4a5f0e1d2c3b4a5f0e1",
    "generatedAt": "2026-02-11T14:22:33.000Z"
  }
}

`customer.shared_record_viewed`

Fired when a customer views a Shared Record link.

json

{
  "event": "customer.shared_record_viewed",
  "timestamp": "2026-02-11T16:45:00.000Z",
  "data": {
    "customerId": "cust_123",
    "viewedAt": "2026-02-11T16:45:00.000Z"
  }
}

Other Customer And Domain Events

The remaining public events use the same envelope and a small data object with the relevant customerId, domain, timestamp, and status fields:

customer.export_downloaded
customer.compare_run
customer.step_up_failed_repeatedly
tenant_domain.activated
tenant_domain.cert_renewal_failed

Next Steps

Signature Verification - Authenticate webhook payloads
Autonomous Agent Pattern - Build agents that react to these events

Event Types

Signature Verification

delta.verified#

Field Reference#

Top-level fields#

delta object#

proof object#

verification object#

period object (conditional)#

usage object (conditional)#

customer.created#

delta.failed#

checkpoint.verified#

receipt.generated#

customer.shared_record_viewed#

Other Customer And Domain Events#

Next Steps#

`delta.verified`

Field Reference

Top-level fields

`delta` object

`proof` object

`verification` object

`period` object (conditional)

`usage` object (conditional)

`customer.created`

`delta.failed`

`checkpoint.verified`

`receipt.generated`

`customer.shared_record_viewed`

Other Customer And Domain Events

Next Steps