Skip to main content
In order to notify your system of asynchronous actions within the Orb platform, Orb provides a 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:
  1. Resource lifecycle changes: Set up entitlements in your service as a result of object creation, such as a subscription.created event.
  2. Balance events: Send out an end-user email when a customer’s pre-paid credit balance is nearing zero.
  3. Data exports: Receive events when an export of resource data to a destination succeeds or fails.
Event types lists every event Orb sends.

Payload format

Webhooks payloads in Orb follow the format:
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 is subscription.action, the payload will contain the serialized subscription resource under the subscription key).

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, which Orb uses to sign every event it sends. By default, all webhook events are sent to every endpoint. Each endpoint also has a payload style, standard or expanded, which sets whether subscriptions and invoices in its events are summarized or serialized in full. New endpoints use standard payloads.

Testing 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.” Webhook test If you need to manually trigger a webhook event to be sent to your server, you can also resend it in the UI. Resend webhook Delivery and retries covers how Orb retries failed deliveries and when it disables a failing endpoint.