What is a Callout Notification?
Zuora provides asynchronous events, delivered as e-mails or callouts, for real-time and scheduled events within the Zuora platform.
Callouts, also known as, webhooks, are event-based API calls that Zuora makes out to other systems, rather than directly to the customers. Callouts can be used by these systems to take information and act upon them based on configured workflows or triggers.
Zuora notification system processes the events in the same order in which they are triggered. But due to certain conditions, such as callout retry, concurrency, and network latency, Zuora does not guarantee that the callout notifications will be delivered in order.
Message Sequence for Callout Basic Authentication
Callout Authentication aligns with the HTTPS protocol RFC 7617.
In BASIC Authentication enabled Callout, the first request from Zuora does not contain the
Authorization header by default. The callout receiving application will return status code 401 along with an authorization
realm parameter. The subsequent request from Zuora contains the
Authorization header specific to the authorization
realm received in the previous request.
See Message sequence for Zuora callout basic authentication for more information.
Preemptive Basic Authentication
Zuora supports the Preemptive Basic Authentication if the Custom Events feature is enabled in your tenant. If you expect that the authorization header contains credentials in the first request that Zuora sends to your callout receiver, take the following steps to enable the preemptive basic authentication for Zuora callouts:
- Contact Zuora Global Support to enable the Preemptive Basic Authentication feature.
- Update the notification that you want to enable the preemptive callout authentication on by the Update a notification definition API. You must set the
truein the request body.
Responses to callouts are truncated down to 60KB before storing them in the database.
Enable Customer Notifications and Callout Permissions
Zuora's callout security measures are built on the combination of HTTPS delivery and the need to authenticate with Zuora API's to retrieve follow-on information.
Zuora will make a callout over HTTPS to a customer-designated URL. HTTPS transport guarantees that no one will intercept the communication. The data transferred over the URL is non-sensitive data, typically an ID for the specific event reported. The recipient of the callout notification will then need to authenticate back with Zuora to retrieve additional information about the event.
Access Notification Setup Options
- Click your user name at the top right-hand side of the application.
- Navigate to Settings > Billing, Settings > Finance, or Settings > Payments.
- Click Setup Profiles, Notifications and Email Templates.
The user locale setting provides an override tenant locale setting. You can change the locale according to your preferred format for display of date and dateTime fields. Refer to the User Locale section of the Manage Users page for more information on what components utilize the User Locale setting.
Configure Event-Specific Options for Callouts
For each event, configure the callout event-specific options. These options include URL, retry flag, protocol, and parameters that you can add to the call.
- On the Setup Notifications and Email Templates page under the Notifications tab, click Edit to set notification configurations for the selected Event.
- On the Edit Notification page, specify the following callout-specific event options:
|Partner Name||Callouts must specify a partner name. Zuora supports callouts using AQuA 1.1 and higher and specifying a partner name enables usage of the latest AQuA. Notification without a partner name is not supported.|
|Callout||Select this option to enable the callout for this event.|
|Base URL||Specify the path to the receiver service of the callout. You must specify a URL using the HTTP Secure (
A maximum of 2048 characters are allowed for the Base URL.
Click add parameter if you want to add parameters to the callout.
When you add parameters, remember the final URL cannot contain white spaces. The URL must be encoded with the URL-safe characters and any other characters encoded with percent-encoding. Otherwise, you might find the -2000 error in the notification history.
For more information about URL characters, see Characters.
See below for an example parameters.
Select the HTTP method to use with the callout. The default value is
|Retry||Select this option to apply the callout retry rules. The default number of retry attempts is 3 at intervals of 30 minutes. Default retry number and intervals can be changed by configuration of the callout options.|
Here's a preview of a callout with parameters.
<?xml version="1.0" encoding="UTF-8"?> <callout> <parameter name="SubscriptionSubscriptionDetailTable"> Subscription.SubscriptionDetailTable </parameter> <parameter name="SubscriptionID"> Subscription.ID </parameter> <parameter name="AccountID"> Account.ID </parameter> </callout>
If you have the Notification and the Configurable Event features enabled in your tenant, Zuora system automatically adds the following fields to the callout header. You can leverage these header fields to trace a callout notification.
|Zuora-Request-Id||uuid without hyphen||Globally identifies a callout request. A different Zuora-Request-Id value is used in any type of retrials. For example, the retrial when connection timeout.|
|X-Amzn-Trace-Id||See AWS request tracing syntax. (Derived from Zuora-Request-Id)||Particularly helps Workflow to trace a callout sent by Notification and the Configurable Event service. The Notification and the Configurable Event service logs the content of it when access logs is enabled.|
|Zuora-Notification-Id||Id of a notification from the Notification and Configurable Event service||Identifies a callout session. The same Zuora-Notification-Id value is used in any type of retrials for the same notification context.|
Zuora supports the following callout authentication that helps you secure your web service calls:
- Basic and NTLM
- OAuth 2.0
If Retry is enabled and Callout Authentication fails, the system will continue retrying.
You can only enable the callout authentication one by one. It is not a global setting. By default, the callout authentication checkboxes are clear and the related fields are hidden and disabled.
Basic and NTLM Authentication
To enable basic or NTLM Callout Authentication:
- Navigate to Settings > Billing (or Payment or Finance) > Setup Profiles, Notifications and Email Templates.
- Click Edit on the notification entry that you want to enable authentication.
- Tick Username/Password on Edit Notification page.
Configure basic or NTLM authentication.
See the following descriptions of the fields to configure basic and NTLM authentication.
|Username (required)||The username associated with the receiver service of the callout.|
|Password (required)||The password associated with the username.|
|Domain (optional)||Domain associated with the username.|
OAuth 2.0 Authentication
Enable OAuth 2.0 Authentication
To enable OAuth 2.0 Authentication for Zuora Callouts:
- Navigate to Z-Billing Settings (or Z-Payment Settings or Z-Finance Settings) > Setup Profiles, Notifications and Email Templates.
- Click Edit on the notification entry that you want to enable authentication.
- Tick OAuth 2.0 on Edit Notification page.
- Select an OAuth 2.0 provider from the provider list if any. Otherwise, add an OAuth 2.0 provider into the list and then select it.
- Click Save.
Add an OAuth 2.0 Provider
Zuora supports the following grant types of OAuth2.0:
- Client Credentials
- Refresh Token
To add an OAuth 2.0 provider of either grant type:
- Click View All Provider on Edit Notification page with OAuth 2.0 ticked, or navigate to Settings > Administration > Manage OAuth 2.0 Providers.
- Click new oauth 2.0 provider on All OAuth 2.0 Providers page.
- Fill in the fields on New OAuth 2.0 Provider page. See the table below for the descriptions of the fields.
- Click Save.
|Name (required)||Name of the new OAuth 2.0 provider.|
|Grant Type (required)||
OAuth 2.0 grant type. Supported grant types:
When Refresh Token is selected, the Refresh Token field will be displayed as a required field.
|Client ID (required)||The client ID that your callout service uses to identify Zuora application|
|Client Secret (required)||The client secret that your callout service uses to authenticate the identity of Zuora application|
Refresh Token (required)
(Applicable only when the grant type is Refresh Token)
The refresh token that you get from your callout service. It allows the client to obtain a new access token without prompting the user authentication.
|Access Token Endpoint (required)||The endpoint that the client uses to obtain an access token given an authorization code.|
|Revoke Endpoint (optional)||The endpoint used by the authenticated client to revoke access and refresh token.|
|Test Endpoint (optional)||The endpoint that you can use to test your configuration.|
|Scope (optional)||Specifies the level of access that Zuora application is requesting.|
Callout Notification Timeout
Every callout has a total of 25 seconds before timing out.
- 10 seconds to establish socket connection
- 15 seconds for data transfer
Currently, the timeout limit cannot be changed. You can change the maximum number of attempts, as well as the time interval between each attempt in Zuora in Settings > Z-Billing Settings > Setup Profiles, Notifications and Email Templates > Callout Options.
Zuora recommends creating asynchronous jobs that run in the background and are independent of callout transactions from Zuora. This is to ensure that your processes are not dependent on the timeframe in which Zuora keeps connections open.
Callout Response Codes
Zuora uses the HTTP response code to determine whether to retry callouts. Zuora only retries a callout if the response code is one of the following:
Additionally, if Confirm success by parsing response content is enabled, Zuora retries a callout if the response code is 200 and the response body contains a
success field that is set to
false. See the "Configure Callout Options" section for more information.
Zuora does not support redirection of callouts via responses with 3xx codes. To change the URL of a callout, edit the callout definition in your Zuora tenant.
Configure Callout Options
Use the Callout Options tab to specify the maximum number of attempts to send the callout. You can also specify the interval at which the attempts will take place.
- On the Setup Notifications and Email Templates page, select the Callout Options tab.
- On the Call-out Options tab, click Edit (on the right side of the screen).
- You can set values for the following parameters:
Default value: disabled
Maximum Number of Delivery Attempts
Specifies the number of times a callout will be tried.
Default value: 3
Maximum value: 5
Minimum Interval between Delivery Attempts
Specifies the number of minutes between callout attempts.
Default value: 30
Maximum allowed minutes: 1440 (i.e., 24 hours)
Confirm success by parsing response content
Controls how Zuora determines the success or failure of callouts to your system.
If enabled, Zuora parses the callout response body when the HTTP response code is 200 and the Content-Type header is set to application/json. Before you enable this option, you must modify your system to include the
successfield in the response body. Click What does...? for more information.
- Click Save.