Skip to main content

Configure Callout Notifications

Zuora

Configure Callout Notifications

  1. Last updated
  2. Save as PDF

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.

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

  1. Click your user name at the top right-hand side of the application.
  2. Navigate to Settings > Billing, Settings > 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

When configuring callout notifications, Zuora allows you to select a pre-configured callout template, eliminating the need to configure callout settings individually.

To create a notification with the callout delivery option, take the following steps:

  1. Click your avatar in the upper right and click Settings > Administration, Settings > Billing, Settings > Finance, or Settings > Payments.
  2. Click Setup Profiles, Notifications and Email Templates.
  3. In the Notifications tab, click Add New Notifications in the Notifications section.
  4. Select a related event from the Related Event list.
  5. Specify the notification name in the Name field.
  6. Select a callout template from the Callout list in the Delivery Options section. If there is no available callout template, you must create one for this event. For more information, see Manage callout templates.
  7. Click Add New Notification.

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.

In addition, you can create custom callout headers in callout templates to deliver additional information in callout notifications. For more information, see Manage callout templates.

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
  • 429
  • 5xx
  • Negative

Note that if the custom request body of callout notifications is invalid, a -2000 response code is returned, and Zuora will neither send the callout notification nor retry it. For more information about Custom Request Entity Body, see Configure event-specific options for callouts.

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. 

  1. Navigate to Administration Settings > Manage Callout Settings.
  2. 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.

  3. Click Save.

Note

Zuora notification system processes the events in the same order in which they are triggered. The timing and order of callout notifications depend on various factors, such as callout retries, concurrency, and network latency. But Zuora guarantees the best performance possible with the right performance boosters and tuning.