Webhooks - Orb

In order to notify your system of asynchronous actions within the Orb platform, Orb provides a powerful, real-time webhooks system that can issue calls to an endpoint of your choosing when certain events take place. Webhooks allow your system or integration to take actions as a result of these events. Orb’s supported webhook events can be useful for a wide variety of use cases:

Resource lifecycle changes: Set up entitlements in your service as a result of object creation, such as a subscription.created event.
Usage patterns: Alert internal teams when a specific usage threshold is hit in a billing period, or when Orb detects an anomalous usage pattern for a customer based on historical patterns.
Balance events: Send out an end-user email when a customer’s pre-paid credit balance is nearing zero.
Data exports: Receive events when an export of resource data to a destination succeeds or fails.

Delivery of Resource lifecycle changes webhooks typically occurs in near real-time, though occasional delays may occur.For alerts on usage, cost, and credit balance, we evaluate alerts (and therefore issue webhooks) several times a day, but the latency guarantee will be a function of your workload. This can be reduced with provisioning for customers on Growth and Enterprise plans.

Webhooks payloads in Orb follow the format:

{
    // Unique to this WebhookEvent resource, and can be used for idempotency (process-once) purposes
    "id": string,
    // ISO8601 `created_at` timestamp of the `WebhookEvent` resource
    "created_at": string,
    // Identifies the type of webhook event being triggered
    "type": string,
    // If a webhook is associated with a resource, the full resource will be serialized
    // in the webhook body.
    "<resource_name>": object,
    // Additional properties specific to this event
    "properties": object,
}

Configuring webhooks

Webhooks are configured to an HTTPS URL on your backend server (note that only the HTTPS scheme is accepted for the production version of your webhook configuration). Each webhook endpoint is associated with a secret (see the X-Orb-Signature clause below). By default, all webhook events are sent to every endpoint.

Debugging webhooks

In the Orb UI, you can test your webhook configuration to ensure that it’s set up properly and ready to receive events from us. From the webhooks portal, you can select on any webhook endpoint to send a “test event.”

If you need to manually trigger a webhook event to be sent to your server, you can also resend it in the UI.

Webhooks retries

Orb guarantees at-least-once delivery for a single webhook event to each of your endpoint. Orb expects a 2xx within five seconds as a successful response to a webhook request. If the request returns an error or otherwise times out, Orb will attempt to retry the event on the following retry schedule, stopping when either retries are exhausted or the request is accepted:

5 seconds
5 minutes
30 minutes
2 hours
5 hours
10 hours
10 hours

In order for your system to handle duplicate notifications, we recommend storing the id of a webhook event temporarily in the webhook consumer and refusing to re-process an event if the same id has already been seen.

Automatic disabling of failing webhook endpoints

Any webhook endpoints that return a 5XX HTTP status codes for more than 99% of deliveries over a 7-day period will be disabled automatically by Orb to preserve system stability. These endpoints can be re-enabled in the Orb UI.

Webhook patterns

Event types follow the pattern <resource_name>.<verb>, where <resource_name> is the root object that is related to the webhook, and the <verb> is the event that has taken place (e.g. customer.created is a newly created Customer resource). By convention, a key in the payload will match the resource_name prefix in type (e.g. if the type issubscription.action, the payload will contain the serialized subscription resource under the subscription key).

Webhook Event Types: Resource Lifecycle Changes

Orb currently issues the following webhooks for resource lifecycle changes:

customer.created

Issued when a customer resource is created.

key	schema
`customer`	Customer
`properties`	`{}`

customer.edited

Issued when a customer is edited. The previous_attributes object will be present and populated with the previous state of any Customer attributes that have changed.

key	schema
`customer`	Customer
`properties.previous_attributes.payment_provider`	`string`
`properties.previous_attributes.payment_provider_id`	`string`
`properties.previous_attributes.auto_collection`	`boolean`
`properties.previous_attributes.email`	`string`
`properties.previous_attributes.name`	`string`
`properties.previous_attributes.email_delivery`	`boolean`
`properties.previous_attributes.metadata`	`object`
`properties.previous_attributes.tax_id`	TaxId
`properties.previous_attributes.shipping_address`	Address
`properties.previous_attributes.billing_address`	Address

customer.balance_transaction_created

Issued when the customer balance changes for an Orb customer. The balance_transaction object will be present and populated with the specific entry that modified the balance.

key	schema
`customer`	Customer
`properties.balance_transaction`	Balance transaction

billable_metric.edited

Issued when a billable metric is edited. This webhook is only issued when metadata for the resource changes, as billable metrics are otherwise immutable. The previous_attributes object will be present and populated with the previous state of any billable metric attributes that have changed.

key	schema
`billable_metric`	Billable metric
`properties.previous_attributes.name`	`string`
`properties.previous_attributes.description`	`string`
`properties.previous_attributes.metadata`	`object`

subscription.created

Issued when a subscription resource is created.

key	schema
`subscription`	Subscription
`properties`	`{}`

subscription.started

Issued when a subscription begins.

key	schema
`subscription`	Subscription
`properties`	`{}`

subscription.fixed_fee_quantity_updated

Issued when a subscription’s fixed fee quantity has been updated.

key	schema
`subscription`	Subscription
`properties.old_quantity`	`number`
`properties.new_quantity`	`number`
`properties.effective_date`	`date-time`
`properties.price_id`	`string`

subscription.edited

Issued when a subscription has been edited. This will not be triggered for changes to pricing.

key	schema
`subscription`	Subscription
`properties.previous_attributes.metadata`	`object`
`properties.previous_attributes.default_invoice_memo`	`string`
`properties.previous_attributes.auto_collection`	`boolean`
`properties.previous_attributes.net_terms`	`number`
`properties.previous_attributes.invoicing_threshold`	`number`

subscription.ended

Occurs whenever a customer’s subscription ends/lapses.

key	schema
`subscription`	Subscription
`properties`	`{}`

subscription.plan_changed

Issued when a scheduled plan change occurs.

key	schema
`subscription`	Subscription
`properties.previous_plan_id`	`string`

subscription.plan_change_scheduled

key	schema
`subscription`	Subscription
`properties.previous_plan_id`	`string`
`properties.new_plan_id`	`string`
`properties.change_date`	`string`

subscription.plan_version_change_scheduled

Issued when a plan version change is scheduled in the future for a subscription.

key	schema
`subscription`	Subscription
`properties.effective_date`	`date-time`
`properties.previous_plan_version_number`	`number`
`properties.new_plan_version_number`	`number`

subscription.plan_version_changed

Issued when a subscription moves to a new plan version.

key	schema
`subscription`	Subscription
`properties.effective_date`	`date-time`
`properties.previous_plan_version_number`	`number`
`properties.new_plan_version_number`	`number`

subscription.trial_ended

Issued when a subscription’s trial ends.

key	schema
`subscription`	Subscription
`properties`	`{}`

subscription.cancellation_scheduled

Issued when a subscription cancellation is scheduled for the future.

key	schema
`subscription`	Subscription
`properties.cancellation_date`	`date-time`

subscription.cancellation_unscheduled

Issued when a previously scheduled subscription cancellation is unscheduled/cancelled.

key	schema
`subscription`	Subscription
`properties.original_cancellation_date`	`date-time`

Unscheduling a cancellation is a lossy operation—the subscription may not fully match its original pre-cancellation state.

invoice.invoice_date_elapsed

Serializing and consuming this webhook can be very expensive in the presence of a large number of subscriptions and is not enabled by default. Please reach out to the Orb team to opt-in to the webhook or discuss the intended workflow.

Issued when the invoice_date of an invoice has elapsed.

key	schema
`invoice`	Invoice
`properties.invoice_date`	`date-time`

invoice.issued

Issued when an invoice transitions to the "issued" state. "issued" invoices are frozen (they cannot be edited, manually or via the API). The automatically_marked_as_paid property will be true when the issued invoice’s amount due is zero, which results in the invoice status being set to paid.

key	schema
`invoice`	Invoice
`properties.automatically_marked_as_paid`	`boolean`

invoice.issue_failed

Issued when an invoice fails to issue.

key	schema
`invoice`	Invoice
`properties.reason`	`string`

invoice.payment_failed

Issued when automated payment collection for an invoice fails for a configured payment gateway.

key	schema
`invoice`	Invoice
`properties.payment_provider`	`"stripe"`
`properties.payment_provider_id`	`string`
`properties.payment_provider_transaction_id`	`string` or `null`

invoice.payment_processing

Issued when a payment for an invoice starts processing.

key	schema
`invoice`	Invoice
`properties.payment_provider`	`"stripe"`
`properties.payment_provider_id`	`string`

invoice.payment_succeeded

Issued when automated payment collection for an invoice succeeds for a configured payment gateway. This webhook is not sent for $0 invoices that are automatically marked as paid upon issuance.

key	schema
`invoice`	Invoice
`properties.payment_provider`	`"stripe"`
`properties.payment_provider_id`	`string`
`properties.payment_provider_transaction_id`	`string`

invoice.edited

Issued when a draft invoice has been edited via the webapp. The previous_attributes object will be present and populated with the previous state of any Invoice attributes that have changed.

key	schema
`invoice`	Invoice
`properties.previous_attributes.amount_due`	`string`
`properties.previous_attributes.subtotal`	`string`
`properties.previous_attributes.total`	`string`
`properties.previous_attributes.discounts`	`array` of Discounts
`properties.previous_attributes.minimum`	Minimum
`properties.previous_attributes.line_items`	`array` of Invoice Line Items
`properties.previous_attributes.net_terms`	`int`
`properties.previous_attributes.due_date`	`date-time`

invoice.manually_marked_as_void

Issued when an invoice is manually marked as void.

key	schema
`invoice`	Invoice
`properties`	`{}`

invoice.manually_marked_as_paid

Issued when an invoice is manually marked as paid.

key	schema
`invoice`	Invoice
`properties.payment_received_date`	`date-time`
`properties.external_id`	`string`
`properties.notes`	`string`

invoice.undo_mark_as_paid

Issued when undoing the Paid status for an invoice that was manually marked as paid.

key	schema
`invoice`	Invoice
`properties`	`{}`

invoice.sync_succeded

Issued when an invoice successfully syncs to the invoice provider.

key	schema
`invoice`	Invoice
`properties.payment_provider`	`"string"`
`properties.payment_provider_id`	`string`

invoice.sync_failed

Issued when an invoice fails to sync to the invoice provider.

key	schema
`invoice`	Invoice
`properties.payment_provider`	`"string"`
`properties.payment_provider_id`	`string`

credit_note.issued

Issued when a credit note is created.

key	schema
`credit_note`	Credit note
`properties`	`{}`

credit_note.marked_as_void

Issued when a credit note is marked as void.

key	schema
`credit_note`	Credit note
`properties`	`{}`

price.edited

Issued when a price is edited. This webhook is only issued when metadata for the resource changes, as prices are otherwise immutable. The previous_attributes object will be present and populated with the previous state of any price attributes that have changed.

key	schema
`price`	Price
`properties.previous_attributes.metadata`	`object`

resource_event.test

Issued via the Orb UI to test if your webhook configuration is set up properly and ready to receive events from us.

key	schema
`message`	`string`

Webhook Event Types: Usage Patterns and Balance Events

Orb currently issues the following usage patterns and balance events webhooks:

subscription.usage_exceeded

Issued when a billable metric in a subscription exceeds a pre-configured quantity threshold.

key	schema
`subscription`	Subscription
`alert_configuration`	Alert
`properties.billable_metric_id`	`string`
`properties.timeframe_start`	`date-time`
`properties.timeframe_end`	`date-time`
`properties.quantity_threshold`	`number`

subscription.cost_exceeded

Issued when a subscription’s accrued spend for a month exceeds a pre-configured currency amount.

Orb will not evaluate alerts on cost that are configured with a threshold below the total of a plan’s fixed costs with a prioritized cadence during billing period rollovers. These alerts can be expected to fire near the first actual usage event received for the new billing period and will subsequently be evaluated several times a day. Please note, prepurchased credits are not included in the spend calculation, and only actual spend will be considered.

key	schema
`subscription`	Subscription
`alert_configuration`	Alert
`properties.timeframe_start`	`date-time`
`properties.timeframe_end`	`date-time`
`properties.amount_threshold`	`number`

customer.credit_balance_depleted

Issued when a customer’s prepaid credit balance is depleted.

key	schema
`customer`	Customer
`alert_configuration`	Alert
`properties.pricing_unit.name`	`string`
`properties.pricing_unit.symbol`	`string`
`properties.pricing_unit.display_name`	`string`

customer.credit_balance_dropped

Issued when a customer’s prepaid credit balance is depleted to a configured threshold.

key	schema
`customer`	Customer
`alert_configuration`	Alert
`properties.balance_threshold`	`string`
`properties.pricing_unit.name`	`string`
`properties.pricing_unit.symbol`	`string`
`properties.pricing_unit.display_name`	`string`

customer.credit_balance_recovered

Issued when a customer’s prepaid credit balance is replenished after depletion.

key	schema
`customer`	Customer
`alert_configuration`	Alert
`properties.pricing_unit.name`	`string`
`properties.pricing_unit.symbol`	`string`
`properties.pricing_unit.display_name`	`string`

Webhook Event Types: Accounting Sync

Orb issues the following webhooks when syncing resources to external accounting systems.

These events are only emitted when the Accounting Sync integration is enabled and configured. Supported connection types are “quickbooks” and “netsuite”. See Accounting and QuickBooks setup guides.

Accounting Sync Record object

The accounting_sync_record included in these events contains the following fields:

key	schema
`id`	`string`
`record_type`	`string`
`sync_action`	`string`
`status`	`string`
`customer_id`	`string`
`provider_customer_id`	`string`
`error_details`	`object`

customer.accounting_sync_succeeded

Issued when a customer successfully syncs to the configured accounting system.

key	schema
`customer`	Customer
`accounting_sync_record`	`object`
`properties.connection_type`	`string` (“quickbooks” or “netsuite”)

customer.accounting_sync_failed

Issued when a customer fails to sync to the configured accounting system.

key	schema
`customer`	Customer
`accounting_sync_record`	`object`
`properties.connection_type`	`string` (“quickbooks” or “netsuite”)
`properties.failure_reason`	`string`

invoice.accounting_sync_succeeded

Issued when an invoice successfully syncs to the configured accounting system.

key	schema
`invoice`	Invoice
`accounting_sync_record`	`object`
`properties.connection_type`	`string` (“quickbooks” or “netsuite”)

invoice.accounting_sync_failed

Issued when an invoice fails to sync to the configured accounting system.

key	schema
`invoice`	Invoice
`accounting_sync_record`	`object`
`properties.connection_type`	`string` (“quickbooks” or “netsuite”)
`properties.failure_reason`	`string`

subscription.accounting_sync_succeeded

Issued when a subscription successfully syncs to the configured accounting system.

key	schema
`subscription`	Subscription
`accounting_sync_record`	`object`
`properties.connection_type`	`string` (“quickbooks” or “netsuite”)

subscription.accounting_sync_failed

Issued when a subscription fails to sync to the configured accounting system.

key	schema
`subscription`	Subscription
`accounting_sync_record`	`object`
`properties.connection_type`	`string` (“quickbooks” or “netsuite”)
`properties.failure_reason`	`string`

transaction.accounting_sync_succeeded

Issued when a transaction successfully syncs to the configured accounting system.

key	schema
`transaction`	`object`
`accounting_sync_record`	`object`
`properties.connection_type`	`string` (“quickbooks” or “netsuite”)

transaction.accounting_sync_failed

Issued when a transaction fails to sync to the configured accounting system.

key	schema
`transaction`	`object`
`accounting_sync_record`	`object`
`properties.connection_type`	`string` (“quickbooks” or “netsuite”)
`properties.failure_reason`	`string`

credit_note.accounting_sync_succeeded

Issued when a credit note successfully syncs to the configured accounting system.

key	schema
`credit_note`	Credit note
`accounting_sync_record`	`object`
`properties.connection_type`	`string` (“quickbooks” or “netsuite”)

credit_note.accounting_sync_failed

Issued when a credit note fails to sync to the configured accounting system.

key	schema
`credit_note`	Credit note
`accounting_sync_record`	`object`
`properties.connection_type`	`string` (“quickbooks” or “netsuite”)
`properties.failure_reason`	`string`

Webhook Event Types: Data Exports

Orb currently issues the following webhooks for data exports:

data_exports.transfer_success

Issued upon a successful transfer of resource data to a destination.

key	schema
`properties.destination_name`	`string`
`properties.description`	`string`
`properties.resources`	`array` of `string`
`properties.rows_transferred`	`number`
`properties.transfer_started_at`	`date-time`
`properties.transfer_ended_at`	`date-time`

data_exports.transfer_error

Issued upon a failed transfer of resource data to a destination.

key	schema
`properties.destination_name`	`string`
`properties.description`	`string`
`properties.resources`	`array` of `string`
`properties.rows_transferred`	`number`
`properties.transfer_started_at`	`date-time`
`properties.transfer_ended_at`	`date-time`
`properties.transfer_blamed_party`	`string`

Webhooks security

Each webhook event sent by Orb also includes two specific headers in the request:

X-Orb-Timestamp: This header represents the time that the webhook was sent from Orb. You can check this timestamp and compare it to a configured threshold in your system, in order to prevent processing of the webhook event. This can be a mitigation against replay attacks where webhook events are re-sent, causing downstream systems to behave unexpectedly.
X-Orb-Signature: The signature header (formatted as v1=<signature>) is a security header which can be used to confirm that the webhook event originated from Orb. We highly recommend verifying the signature, and only processing events where the header matches the signature you generate. Since each webhook endpoint is associated with a secret, your backend server should re-compute the signature by preparing the payload and subsequently computing an HMAC with the SHA 256 function.
- The payload for the HMAC is the literal "v1:" followed by the ISO format X-Orb-Timestamp and finally the literal : followed by the event message body itself.
- You should use the configured secret for the endpoint URL as the signing secret for the HMAC.
- When comparing to your generated HMAC, you can either prefix the literal v1= to compare with X-Orb-Signature header directly, or extract the element after v1= in X-Orb-Signature to check against your generated value.

Webhooks verification

Orb’s SDKs provide verification methods for your webhook events, available in Python, Node, and Go. Here’s an example verification snippet implemented as a Flask endpoint:

from flask import Flask, request
import hmac
from hashlib import sha256

app = Flask(__name__)

# Example Using Flask
@app.route('/webhook-handler', methods=['POST'])
def handle_webhook():
    # parse webhook JSON
    webhook_event = request.json

    if webhook_event is None: 
        # could not parse request
        return ('Unable to parse notification.', 400)

    expected_signature = request.headers["X-Orb-Signature"]
    iso_format_delivery_time = request.headers["X-Orb-Timestamp"]

    secret_string = "<insert your secret string here>"  
    secret = bytes(secret_string, "utf-8")

    # Prefix the beginning of the signature with `v1:<isoformat timestamp>`
    prefix = "v1:{0}:".format(iso_format_delivery_time)

    # Convert to bytes and append the body of the request
    message = prefix.encode("utf-8") + request.data

    # Generate an encode message based on the secret and the message string with sha256.
    hmac_object = hmac.new(secret, message, sha256)
    created_signature = "v1=" + hmac_object.hexdigest()
    
    if not expected_signature == created_signature:
        return ('Unable to verify webhook signature.', 400)
    
    # Handle based on webhook_event.type
    return ('Successfully processed webhook!', 200)

Integrations and exports

​Configuring webhooks

​Debugging webhooks

​Webhooks retries

​Automatic disabling of failing webhook endpoints

​Webhook patterns

​Webhook Event Types: Resource Lifecycle Changes

​customer.created

​customer.edited

​customer.balance_transaction_created

​billable_metric.edited

​subscription.created

​subscription.started

​subscription.fixed_fee_quantity_updated

​subscription.edited

​subscription.ended

​subscription.plan_changed

​subscription.plan_change_scheduled

​subscription.plan_version_change_scheduled

​subscription.plan_version_changed

​subscription.trial_ended

​subscription.cancellation_scheduled

​subscription.cancellation_unscheduled

​invoice.invoice_date_elapsed

​invoice.issued

​invoice.issue_failed

​invoice.payment_failed

​invoice.payment_processing

​invoice.payment_succeeded

​invoice.edited

​invoice.manually_marked_as_void

​invoice.manually_marked_as_paid

​invoice.undo_mark_as_paid

​invoice.sync_succeded

​invoice.sync_failed

​credit_note.issued

​credit_note.marked_as_void

​price.edited

​resource_event.test

​Webhook Event Types: Usage Patterns and Balance Events

​subscription.usage_exceeded

​subscription.cost_exceeded

​customer.credit_balance_depleted

​customer.credit_balance_dropped

​customer.credit_balance_recovered

​Webhook Event Types: Accounting Sync

​Accounting Sync Record object

​customer.accounting_sync_succeeded

​customer.accounting_sync_failed

​invoice.accounting_sync_succeeded

​invoice.accounting_sync_failed

​subscription.accounting_sync_succeeded

​subscription.accounting_sync_failed

​transaction.accounting_sync_succeeded

​transaction.accounting_sync_failed

​credit_note.accounting_sync_succeeded

​credit_note.accounting_sync_failed

​Webhook Event Types: Data Exports

​data_exports.transfer_success

​data_exports.transfer_error

​Webhooks security

​Webhooks verification

Configuring webhooks

Debugging webhooks

Webhooks retries

Automatic disabling of failing webhook endpoints

Webhook patterns

Webhook Event Types: Resource Lifecycle Changes

customer.created

customer.edited

customer.balance_transaction_created

billable_metric.edited

subscription.created

subscription.started

subscription.fixed_fee_quantity_updated

subscription.edited

subscription.ended

subscription.plan_changed

subscription.plan_change_scheduled

subscription.plan_version_change_scheduled

subscription.plan_version_changed

subscription.trial_ended

subscription.cancellation_scheduled

subscription.cancellation_unscheduled

invoice.invoice_date_elapsed

invoice.issued

invoice.issue_failed

invoice.payment_failed

invoice.payment_processing

invoice.payment_succeeded

invoice.edited

invoice.manually_marked_as_void

invoice.manually_marked_as_paid

invoice.undo_mark_as_paid

invoice.sync_succeded

invoice.sync_failed

credit_note.issued

credit_note.marked_as_void

price.edited

resource_event.test

Webhook Event Types: Usage Patterns and Balance Events

subscription.usage_exceeded

subscription.cost_exceeded

customer.credit_balance_depleted

customer.credit_balance_dropped

customer.credit_balance_recovered

Webhook Event Types: Accounting Sync

Accounting Sync Record object

customer.accounting_sync_succeeded

customer.accounting_sync_failed

invoice.accounting_sync_succeeded

invoice.accounting_sync_failed

subscription.accounting_sync_succeeded

subscription.accounting_sync_failed

transaction.accounting_sync_succeeded

transaction.accounting_sync_failed

credit_note.accounting_sync_succeeded

credit_note.accounting_sync_failed

Webhook Event Types: Data Exports

data_exports.transfer_success

data_exports.transfer_error

Webhooks security

Webhooks verification