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

When using Basic authentication in callout notifications, Zuora transmits credentials with the Authorization field in HTTP request headers. The format of the header field is as follows:

Authorization: Basic <username:password>

The <username:password> is a base64-encoded string.

Zuora does not provide the Authorization field in the first HTTP request by default when sending a callout notification. The callout receiver responds to Zuora with a 401 response. The response must contain a WWW-Authenticate header field with a realm value indicating the protection scope. Then, Zuora sends a second HTTP request to the callout receiver with the Authorization field in the request header.

If you want Zuora to provide the Authorization field in the first HTTP request, enable the Enable Preemptive Authentication setting when creating or editing a callout notification. For more information, see Basic and NTLM Authentication.

For more information about the Basic authentication scheme, see RFC 7617.

For more information about Zuora callout message sequence, see Message sequence for Zuora callout basic authentication.

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 they 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.

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.

Navigate to Settings > Billing, Settings > Finance, or Settings > Payments.
Click Setup Profiles, Notifications and Email Templates.
Click Add New Notification to create a new notification and select an event from the Related Event dropdown list, or click Edit to configure an existing notification.
In the Delivery Options section, specify the following callout-specific event options:

Field	Description
Callout	Select this option to enable the callout for this event.
Merge Field Merge Field Tag	Merge fields can be used in the callout Base URL or the callout request body. Select the intended merge field from the dropdown list, and the corresponding merge field tag is automatically displayed on the right. You can copy the populated merge field tag from the Merge Field Tag field and paste it into the Base URL field or in the Custom Request Entity Body text box.
Base URL	Specify the path to the receiver service of the callout. You must specify a URL using the HTTP Secure (`https://`) protocol. Do not specify a port when entering the URL. Zuora does not support custom ports. You must use the port number 443. Zuora also supports merge fields in the base URL. For example, you can specify a base URL as `https://mywebsite.com/zuora/<DataSource.Account.Id>`. A maximum of 2048 characters are allowed for the Base URL.
Http Method	Select the HTTP method to use with the callout. The default value is `POST`. Zuora supports the `POST`, `GET`, `PUT`, 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.
{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.
Body Format	Currently, only application/json is supported.
Preview	Click Preview to preview the detailed callout request information, including the default request entity body.
Exit Preview	Click Exit Preview to close the detailed callout request information. Note that this button is only available after Preview is clicked.
Overwrite Body	Click Overwrite Body to display the Custom Request Entity Body checkbox and text box. Note that this button is only available after Preview is clicked.
Custom Request Entity Body	You can customize the fields to be included in the callout request body so that the JSON structure can be recognized by outbound systems. The Custom Request Entity Body checkbox and text box are only available after Overwrite Body is clicked. With this checkbox selected, you can type the custom request body in the text box as needed. Note that invalid formatted callout notifications cannot be sent, and a -2000 error code will be reported within the Callout History tab.
Allow Retry	Select this check box 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 configuring callout settings.
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.

The following table describes a preview of a callout with parameters.

Content-Encoding:	utf-8
Content-Type:	application/json
data:	{ "AccountId":"DataSource.Account.Id", "SubscriptionId":"DataSource.Subscription.Id", "SubscriptionPreviousSubscriptionId":"DataSource.Subscription.PreviousSubscriptionId", "ParentAccountId":"DataSource.ParentAccount.Id", "DefaultPaymentMethodId":"DataSource.DefaultPaymentMethod.Id" }

Content-Encoding:

utf-8

Content-Type:

application/json

data:

{
"AccountId":"DataSource.Account.Id",
"SubscriptionId":"DataSource.Subscription.Id",
"SubscriptionPreviousSubscriptionId":"DataSource.Subscription.PreviousSubscriptionId",
"ParentAccountId":"DataSource.ParentAccount.Id",
"DefaultPaymentMethodId":"DataSource.DefaultPaymentMethod.Id"
}

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:

Navigate to Settings > Billing (or Payment or Finance) > Setup Profiles, Notifications and Email Templates.
Click Edit of a specific notification you want to enable authentication for.
In the Delivery Options section, select the Username/Password checkbox.
Configure basic or NTLM authentication.
See the following table for required fields and field descriptions.
Click Save.

Fields in the following table are available only if the Username/Password checkbox is selected when creating or editing a callout notification.

Field	Basic authentication	NTLM authentication	Description
Username	Required	Required	The username associated with the receiver service of the callout.
Password	Required	Required	The password associated with the username.
Domain	(N/A)	Optional	The domain which contains multiple users in an NTLM-authentication-enabled system.
Enable Preemptive Authentication	Optional	Optional	If this checkbox is selected, Zuora transmits credentials in the first HTTP request when sending callout notifications to the callout receiver. The credential, a combination of username and password in base64 format, is sent in the `Authentication` header field. Note that Zuora does not provide the `Authorization` field in the first HTTP request by default. For more information, see Message sequence for callout basic authentication.

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.

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

Provide OAuth 2.0 client credentials

When a callout notification is triggered, Zuora sends an HTTP request to the OAuth 2.0 Provider, with the client ID and secret in the request body. If the request fails, Zuora sends another HTTP request with these credentials in the request header, using the HTTP Basic authentication scheme:
Authorization: Basic <client_id:client_secret>
Note that <client_id:client_secret> is a base64-encoded string.

For example, if your client_id is username and client_secret is password, the HTTP Basic authentication scheme is as follows:
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

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 Administration Settings > Manage Callout Settings.

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 Settings" 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 Settings

Use the Manage Callout Settings tab to specify the maximum number of attempts to send callout notifications. You can also specify the interval at which the attempts will take place.

Navigate to Administration Settings > Manage Callout Settings.
On the Callout Settings page, you can set values for the following parameters:
- 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 (which is, 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.
- For custom event triggered callouts, send empty strings as "null"
  
  With this setting enabled, all empty strings in callouts triggered by custom events are returned as "null". This setting applies not only to custom events created by you in your Zuora tenant, but also to pre-defined custom events created by Zuora, such as Order Processed or Order Action Processed.
  Note that Zuora recommends that you set returned empty strings as "null" for consistency with standard callout notifications.
Click Save.