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.
Zuora supports the Preemptive Basic Authentication feature if the Notification and the Configurable Event features are enabled in your tenant. If you expect that Zuora sends out an Authorization header field containing credentials in the first request to your callout receiver, contact Zuora Global Support to enable Preemptive Basic Authentication. Otherwise, the callout receiver will return a 400 response indicating that the authorization token is not present in the first request.
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.
Zuora's callout system does not implement SNI. If you configure your system to route callout requests according to SNI host information, the callouts will fail.
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 (
URL Allowed Number of Characters
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.|
|Callout Authentication||Enables basic authentication with Username, Password, and Domain (for NTLM) in the header of the posted notification. Refer to the description below.|
Here's a preview of a callout with parameters.
|<?xml version="1.0" encoding="UTF-8"?>
Enable Callout Authentication
Callout Authentication lets you make secure web service calls using a basic login. Zuora supports the following authentication types:
You can enable Callout Authentication through Z-Billing Settings (or Z-Payment Settings or Z-Finance Settings) > Setup Profiles, Notifications and Email Templates.
Callout Authentication must be enabled for every callout. It is not a global setting. By default, the Callout Authentication check box is clear and the related fields are disabled.
|Callout Authentication||Select this option to enable Callout 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.|
If Retry is enabled and Callout Authentication fails, the system will continue retrying.
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.