Governance And Events

This group covers control and observation around execution. Read it in outcome order: define governance before execution, inspect approval work when control cases are created, and use events plus webhook delivery to observe what the runtime actually did.

Control And Delivery

Create policy rule

Governance definition. Create a policy when execution rules must be expressed through canonical control-plane resources instead of hidden tenant logic.

Request URL

POST
POST https://b2b.youhodler.com/api/policy-rules

Request Body

application/json
{
  "name": "Large crypto withdrawal approval",
  "description": "Require compliance review for large crypto withdrawals",
  "conditions": [
    {
      "amount_basis": "usd_equivalent",
      "kind": "amount_threshold",
      "operator": "gte",
      "threshold": {
        "currency": "USD",
        "value": "10000.00"
      }
    },
    {
      "asset_class": "crypto",
      "asset_role": "principal",
      "kind": "asset_class"
    }
  ],
  "decision": {
    "approver_role_ref": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "initiator_cannot_approve": true,
    "kind": "require_approval",
    "reason": "large_crypto_withdrawal",
    "threshold": 2
  },
  "operation_type": "withdrawal",
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}

Response

application/json
{
  "name": "Large crypto withdrawal approval",
  "description": "Require compliance review for large crypto withdrawals",
  "activated_at": null,
  "conditions": [
    {
      "amount_basis": "usd_equivalent",
      "kind": "amount_threshold",
      "operator": "gte",
      "threshold": {
        "currency": "USD",
        "value": "10000.00"
      }
    },
    {
      "asset_class": "crypto",
      "asset_role": "principal",
      "kind": "asset_class"
    }
  ],
  "created_at": "2026-05-01T10:00:00Z",
  "decision": {
    "approver_role_ref": "roles/44444444-4444-4444-8444-444444444444",
    "initiator_cannot_approve": true,
    "kind": "require_approval",
    "reason": "large_crypto_withdrawal",
    "threshold": 2
  },
  "etag": "policy-rule-v2-0001",
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "operation_type": "withdrawal",
  "resource": "policy_rule",
  "retired_at": null,
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "status": "draft",
  "updated_at": "2026-05-01T10:00:00Z",
  "version": 1
}

List approvals

Pending decision work. List approvals when governed execution has created review cases and operators need the current queue of unresolved work.

Request URL

GET
GET https://b2b.youhodler.com/api/approvals?scope_ref=enterprises/11111111-1111-4111-8111-111111111111&status=pending

Response

application/json
{
  "items": [
    {
      "action_family": "withdrawal",
      "collected_human_approvals": 0,
      "created_at": "2026-05-01T10:00:00Z",
      "decision": null,
      "expires_at": "2026-05-02T10:00:00Z",
      "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "initiated_by": {
        "actor": null,
        "approved_by": null,
        "authenticated_principal": {
          "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "kind": "user",
          "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        },
        "enterprise_binding": {
          "tenant_type": "enterprise",
          "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        },
        "federation": null,
        "identity_source": "platform-managed",
        "initiated_by": null,
        "subject": {
          "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "kind": "user",
          "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        }
      },
      "operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "requirement_snapshot": {
        "authority_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "expires_at": "2026-05-02T10:00:00Z",
        "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "initiator_cannot_approve": true,
        "reason_code": "high_value",
        "required_human_approvals": 1,
        "requirement_key": "withdrawal_approval",
        "source": "policy"
      },
      "resource": "approval",
      "status": "pending",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ],
  "next_page_token": null
}

Approve approval

Explicit governance decision. Approve a pending approval when a governed operation should be released to continue through runtime execution.

Request URL

POST
POST https://b2b.youhodler.com/api/approvals/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/approve

Request Body

application/json
{
  "reason": "Reviewed request"
}

Response

application/json
{
  "action_family": "withdrawal",
  "collected_human_approvals": 1,
  "created_at": "2026-05-01T10:00:00Z",
  "decision": {
    "decided_at": "2026-05-01T10:00:00Z",
    "decided_by": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "11111111-1111-4111-8111-111111111111",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "11111111-1111-4111-8111-111111111111",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "reason": "Approved after review"
  },
  "expires_at": "2026-05-02T10:00:00Z",
  "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "initiated_by": {
    "actor": null,
    "approved_by": null,
    "authenticated_principal": {
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "kind": "user",
      "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "enterprise_binding": {
      "tenant_type": "enterprise",
      "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "federation": null,
    "identity_source": "platform-managed",
    "initiated_by": null,
    "subject": {
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "kind": "user",
      "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    }
  },
  "operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "requirement_snapshot": {
    "authority_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "expires_at": "2026-05-02T10:00:00Z",
    "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "initiator_cannot_approve": true,
    "reason_code": "high_value",
    "required_human_approvals": 1,
    "requirement_key": "withdrawal_approval",
    "source": "policy"
  },
  "resource": "approval",
  "status": "approved",
  "updated_at": "2026-05-01T10:00:00Z"
}

List events

Replay-safe audit history. List events when an integration needs canonical lifecycle history, delayed reconciliation, or traceable replay after runtime changes.

Request URL

GET
GET https://b2b.youhodler.com/api/events?scope_ref=enterprises/11111111-1111-4111-8111-111111111111&page_size=20

Response

application/json
{
  "items": [
    {
      "aggregate": {
        "type": "withdrawal",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "data": {
        "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "failure_reason": null,
        "family": "withdrawal",
        "fee_summary": {
          "components": [
            {
              "amount": {
                "currency": "USDC",
                "value": "1.00"
              },
              "kind": "network_fee"
            }
          ],
          "total": {
            "currency": "USDC",
            "value": "1.00"
          }
        },
        "fill_rate": null,
        "occurred_at": "2026-05-01T10:00:00Z",
        "operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "principal_amount": {
          "currency": "USDC",
          "value": "250.00"
        },
        "scope_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "status": "settled"
      },
      "event_type": "operations.withdrawal.settled.v1",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "metadata": null,
      "occurred_at": "2026-05-01T10:00:00Z",
      "partition_key": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "published_at": "2026-05-01T10:00:00Z",
      "resource": "event",
      "schema_version": 1,
      "scope_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "subject_attribution": {
        "actor": null,
        "approved_by": null,
        "authenticated_principal": {
          "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "kind": "user",
          "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        },
        "enterprise_binding": {
          "tenant_type": "enterprise",
          "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        },
        "federation": null,
        "identity_source": "platform-managed",
        "initiated_by": null,
        "subject": {
          "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "kind": "user",
          "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        }
      },
      "trace_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    }
  ],
  "next_page_token": null
}

Create webhook subscription

Push delivery target. Create a webhook subscription when the tenant needs runtime state changes pushed into an external system instead of only pulled later from the event log.

Request URL

POST
POST https://b2b.youhodler.com/api/webhook-subscriptions

Request Body

application/json
{
  "event_types": [
    "operations.withdrawal.settled.v1"
  ],
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "secret": "wh_secret_placeholder",
  "url": "https://example.com/webhooks"
}

Response

application/json
{
  "created_at": "2026-05-01T10:00:00Z",
  "etag": "2026-05-01T10:00:00Z",
  "event_types": [
    "operations.withdrawal.settled.v1"
  ],
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "kind": "public",
  "managed_by": null,
  "resource": "webhook_subscription",
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "signing": "hmac",
  "status": "active",
  "updated_at": "2026-05-01T10:00:00Z",
  "url": "https://example.com/webhooks"
}

Enable webhook subscription

Delivery activation. New subscriptions are active. Re-enable a disabled subscription when delivery should resume.

Request URL

POST
POST https://b2b.youhodler.com/api/webhook-subscriptions/ccccccc3-cccc-4ccc-8ccc-ccccccccccc3/enable
Authorization: Bearer <token>
If-Match: <etag from the subscription>

Response

application/json
{
  "created_at": "2026-05-01T10:00:00Z",
  "etag": "2026-05-01T10:00:00Z",
  "event_types": [
    "operations.withdrawal.settled.v1"
  ],
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "kind": "public",
  "managed_by": null,
  "resource": "webhook_subscription",
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "signing": "hmac",
  "status": "active",
  "updated_at": "2026-05-01T10:00:00Z",
  "url": "https://example.com/webhooks"
}