Skip to main content

Configure Callout Notifications


Configure Callout Notifications

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.

Responses to callouts are truncated down to 60KB before storing them in the database.

Enable Customer Notifications and Callout Permissions

Callout Security

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

  1. Click your user name at the top right-hand side of the application.
  2. Navigate to Settings > BillingSettings > Finance, or Settings > Payments.
  3. Click Setup Profiles, Notifications and Email Templates

Basic Information

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.

  1. On the Setup Notifications and Email Templates page under the Notifications tab, click Edit to set notification configurations for the selected Event.
  2. On the Edit Notification page, specify the following callout-specific event options:
Field Description
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 (https://) protocol. See Sample Code for Callout Receiver for an example of code used to create a callout receiver. Do not specify a port when entering the URL. Zuora does not support custom ports. You must use the port number 443.

A maximum of 2048 characters are allowed for the Base URL.

{add parameter}
Parameter Name
Parameter Value

Click add parameter if you want to add parameters to the callout.

  • Parameter Name: Specify a field name. This field defaults to a name associated with the Value.
  • Parameter Value: Select an item from the list of object and field names that can be passed in as parameters. See here for descriptions of data source objects and fields. For information on system fields, refer to Email Template Merge Fields.

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.

HTTP Method

Select the HTTP method to use with the callout. The default value is POST. Zuora supports the POSTGETPUT, and DELETE methods. The customer API response to the Zuora callout must be HTTP status code 200, or the system considers the callout as a failure.

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
  • Username/Password

    Enables basic authentication with Username, Password, and Domain (for NTLM) in the header of the posted notification. See the "Callout Authentication" section below for the details.

  • OAuth 2.0

    Enable OAuth 2.0 authentication. See the "Callout Authentication" section below for the details.


Here's a preview of a callout with parameters.






<?xml version="1.0" encoding="UTF-8"?>


                <parameter name="SubscriptionSubscriptionDetailTable">



                <parameter name="SubscriptionID">



                <parameter name="AccountID">




Callout Header

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.

Header field Format Description
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.

Callout Authentication

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:

  1. Navigate to Settings > Billing (or Payment or Finance> Setup Profiles, Notifications and Email Templates.
  2. Click Edit on the notification entry that you want to enable authentication.
  3. Tick Username/Password on Edit Notification page.
  4. Configure basic or NTLM authentication.
  5. Click Save.

See the following descriptions of the fields to configure basic and NTLM authentication. 

Field Description
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.

Enable Preemptive Authentication (optional)

If enabled, Zuora includes authentication credentials in the first request to the callout receiver.

OAuth 2.0 Authentication

Enable OAuth 2.0 Authentication

To enable OAuth 2.0 Authentication for Zuora Callouts: 

  1. Navigate to Z-Billing Settings (or Z-Payment Settings or Z-Finance Settings> Setup Profiles, Notifications and Email Templates.
  2. Click Edit on the notification entry that you want to enable authentication.
  3. Tick OAuth 2.0 on Edit Notification page.

  4. 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.
  5. Click Save.

For more information about how to create an OAuth provider, see Add an OAuth 2.0 Provider.

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:

  • 1xx
  • 403
  • 408
  • 5xx
  • Negative

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. 

  1. On the Setup Notifications and Email Templates page, select the Callout Options tab.
  2. On the Call-out Options tab, click Edit (on the right side of the screen).
  3. 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 success field in the response body. Click What does...? for more information.

  4. Click Save.