Uber Developers

Billing Policy Webhook

WEBHOOK: POSThttps://<YOUR_WEBHOOK_URI> event_type: direct.organization

A webhook of type direct.organization will be sent in real time whenever the billing policy or tax form completion status changes on a sub-organization.

The webhook supports two types of updates:

Billing status changes: When a sub-organization’s billing policy transitions between active and inactive.
Tax form completion: When a sub-organization completes its required tax form, transitioning from false to true.

Both updates are delivered through the same webhook event. Inspect the attribute_name field of each entry in data.changes to identify which attribute triggered the event.

¶ Sample Webhook

The webhook is sent as a POST request with the following JSON payload.

¶ Example 1: Billing Policy Activation

{
  "id": "d1458cc4-dc66-476d-b6a8-87f696646a2f",
  "type": "direct.organization",
  "schema_version": "2.0",
  "timestamp": "2026-03-30T17:45:40.000Z",
  "data": {
    "organization_uuid": "222516e9-b49d-4e9f-80dd-2c7b4c41e532",
    "organization_name": "billing webhook org for testing2",
    "root_org_uuid": "6ab229b4-20ff-59fa-b153-1723a9668a4b",
    "tenancy": "uber/testing/direct/6ab229b4-20ff-59fa-b153-1723a9668a4b",
    "billing_status": "active",
    "is_tax_form_completed": true,
    "changes": [
      {
        "attribute_name": "b2b_billing_info.policies_metadata",
        "operation": "UPDATE",
        "previous_value": "inactive",
        "current_value": "active"
      }
    ]
  }
}

¶ Example 2: Tax Form Completion

{
  "id": "e2569dd5-ec77-487e-a4e5-91a2345bc012",
  "type": "direct.organization",
  "schema_version": "2.0",
  "timestamp": "2026-03-30T17:50:40.000Z",
  "data": {
    "organization_uuid": "222516e9-b49d-4e9f-80dd-2c7b4c41e532",
    "organization_name": "billing webhook org for testing2",
    "root_org_uuid": "6ab229b4-20ff-59fa-b153-1723a9668a4b",
    "tenancy": "uber/testing/direct/6ab229b4-20ff-59fa-b153-1723a9668a4b",
    "billing_status": "active",
    "is_tax_form_completed": true,
    "changes": [
      {
        "attribute_name": "organization.direct_organization.base_info.is_tax_form_completed.value",
        "operation": "UPDATE",
        "previous_value": "false",
        "current_value": "true"
      }
    ]
  }
}

¶ Fields Definition

Field	Type	Description
`id`	string	Unique identifier (UUID) for this event instance.
`type`	string	The type of webhook event. Always `direct.organization`.
`schema_version`	string	Version of the event schema (currently `2.0`).
`timestamp`	string	ISO 8601 timestamp indicating when the event was generated.
`data`	object	Organization details and the list of changes. Please refer to the Data Object Definition for more information.

¶ Data Object Definition

Field	Type	Description
`organization_uuid`	string	UUID of the sub-organization where the change occurred.
`organization_name`	string	Human-readable name of the sub-organization.
`root_org_uuid`	string	UUID of the root organization that owns the sub-organization.
`tenancy`	string	Tenancy path identifying the environment and root organization (e.g. `uber/production/direct/<root_org_uuid>`).
`billing_status`	string	Current billing policy status. Possible values: `active`, `inactive`.
`is_tax_form_completed`	boolean	Current tax form completion status. `true` indicates the tax form is completed; `false` indicates it is incomplete.
`changes`	array	List of attributes that changed and triggered the webhook. Please refer to the Changes Object Definition for more information.

Note: billing_status and is_tax_form_completed represent the current state of the sub-organization, regardless of which attribute triggered the webhook. Use these fields to understand the overall billing and tax form status.

¶ Changes Object Definition

Each entry in the changes array represents a single attribute that was modified:

Field	Type	Description
`attribute_name`	string	The fully qualified name of the attribute that changed. See Supported Attributes.
`operation`	string	Always `UPDATE`.
`previous_value`	string	The value of the attribute before the change.
`current_value`	string	The value of the attribute after the change.

¶ Supported Attributes

The supported attributes and their possible transitions are:

Attribute Name	Previous Value	Current Value	Description
`b2b_billing_info.policies_metadata`	`inactive`	`active`	Billing policy activated.
`b2b_billing_info.policies_metadata`	`active`	`inactive`	Billing policy deactivated.
`organization.direct_organization.base_info.is_tax_form_completed.value`	`false`	`true`	Tax form completed.

¶ Delivery Rules

¶ Organizations Without Mandatory Tax Form Requirements

For organizations where tax form completion is not mandatory, the webhook is triggered whenever the billing policy transitions between active and inactive.

¶ Organizations With Mandatory Tax Form Requirements

For organizations included in the tax form rollout, webhook delivery requires the billing policy to be active and the tax form to be completed, except when notifying partners of a subsequent billing deactivation.

Trigger	Billing Status After Change	Tax Form Completed	Webhook Delivered
Billing activated	`active`	`true`	Yes
Billing activated	`active`	`false`	No
Billing deactivated	`inactive`	`true`	Yes
Tax form completed (`false` → `true`)	`active`	`true`	Yes

¶ Additional Considerations

Billing policy updates: Changes to billing details (such as rates or tiers) do not trigger this webhook if the billing policy remains active.
Event identification: Always inspect data.changes[].attribute_name to determine whether the webhook was triggered by a billing policy change or tax form completion.
Current state: Use data.billing_status and data.is_tax_form_completed to determine the organization’s current billing and tax form completion status.

For details on setting up your webhook endpoint, verifying the webhook signature, and retry behavior, please refer to the Webhooks Overview.