Knowledge Center

Knowledge Center > RBM Solutions > Notifications > Configure Callout Notifications

Configure Callout Notifications

What is a Callout Notification?

Zuora enables asynchronous e-mails and 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 other systems to take information and act upon as configured by workflows and triggers.

Zuora notification system processes the events in the same order as which they are triggered. But for certain conditions, such as callout retry, concurrency, and network latency, Zuora does not guarantee that the callout notifications are sent out in order.

Callout Authentication aligns with the HTTPS protocol https://www.ietf.org/rfc/rfc2617.txt

In BASIC or DIGEST Authentication enabled Callout, the first request from Zuora does not contain the Authorization header. The callout receiving application will return status code 401 along with authorization realm parameter. The subsequent request from Zuora contains the authorization header specific to the authorization realm received in the previous request.

Customer 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

In Zuora, select Settings > Z-Billing Settings (or Z-Payments Settings or Z-Finance Settings> Setup Profiles, Notifications and Email Templates. The Setup Notifications and Email Templates page appears.

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.
URL Allowed Number of Characters

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

Content-Encoding:
utf-8
Content-Type:
text/xml
data:
<?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>

Enable Callout Authentication

Callout Authentication lets you to make secure web service calls using a basic login. Zuora supports the following authentication types:

  • Basic
  • Digest
  • NTLM

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_parameters.png

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. 

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

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.
Last modified
22:35, 22 Nov 2016

Tags

Classifications

(not set)