Manage callout templates

View callout templates

You can view all callout templates on the Callout Templates page.

To open the Callout Templates page, perform the following steps:

1. Click your avatar in the upper right and navigate to Settings > Administration, Settings > Billing, Settings > Finance, or Settings > Payments.
2. Click Setup Profiles, Notifications and Email Templates.
3. Click the Callout Templates tab. The Callout Templates page opens.

This page displays all callout templates, with detailed information on each template, such as the template name, description, related notifications, and status.

Create a callout template

To create a callout template, perform the following steps:

1. On the Callout Templates page, click + Add New Callout Template.
2. In the displayed Create Callout Template dialog, configure the following settings:
   • Basic information:

     Field	Required?	Description
     Name	Yes	Specify the name of the callout template. The name must be unique across all callout templates.
     Related Event	Yes	Select a standard or custom event associated with the callout template from the dropdown list. In the dropdown list, events are grouped into the following categories: Billing Finance Payments System
     Description		Specify the description of the callout template.
     Active		Switch the toggle to activate or inactivate the callout template. Zuora will not trigger callout notifications if the associated callout template is inactive.

   • Available merge fields:

     Field	Required?	Description
     Field Type		Select an object on which the merge field you want to use is defined. The available objects vary depending on the callout template’s related event. For more information, see Add merge fields to a callout template.
     Field		Select the merge field. You must select the field type before specifying the merge field. For more information, see Add merge fields to a callout template.
     Merge Field Tag		When the Field Type and Field fields are specified, Zuora auto-generates and displays the corresponding merge field string in this field. You can copy the merge field tag and paste it into the Request URL and Request Body fields or the Header Name and Header Value fields of custom callout headers. For more information, see Add merge fields to a callout template.

   • Request information:

     Field	Required?	Description
     Http Method	Yes	Select the HTTP method to use with the callout. The default value is POST. Zuora supports the following methods: POST GET PUT PATCH DELETE The customer API response to the Zuora callout must be HTTP status code 200, or the system considers the callout as a failure.
     Request URL	Yes	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 in the URL because Zuora always uses port 443 to send callout notifications. You cannot override the port number. Zuora supports adding merge fields to the request URL. For example, you can specify a request URL as https://mywebsite.com/zuora/{{DataSource.Account.Id}}.  For more information, see Add merge fields to a callout template. A maximum of 1000 characters is allowed for the request URL.

   • Request body:

     Field	Required?	Description
     Merge Fields		Select the merge fields you want to include in the callout request body from the list. For more information, see Add merge fields to a callout template.

   • Request Authentication:
     Some fields in the following table apply only to specific authentication types. For more information, see Callout authentication.

     Field	Required?	Description
     Authentication Type		Select the callout authentication type from the list. Valid options are as follows: None Username/Password OAuth 2.0
     Username	This field is required if the Authentication Type is Username/Password.	Specify the username associated with the callout receiver service. This field applies only to the Username/Password authentication type.
     Password	This field is required if the Authentication Type is Username/Password.	Specify the password associated with the username. This field applies only to the Username/Password authentication type.
     Domain		Specify the domain that contains multiple users in an NTLM-authentication-enabled system. This field applies only to the Username/Password authentication type.
     Enable Preemptive Authentication		If this checkbox is selected, Zuora transmits credentials in the Authentication header field in the first HTTP request when sending callout notifications to the callout receiver. The credential is a combination of username and password in base64 format. 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. This field applies only to the Username/Password authentication type.
     Provider Name	This field is required if the Authentication Type is OAuth 2.0.	Select an OAuth 2.0 provider from the provider list. This field applies only to the OAuth 2.0 authentication type.

   • Additional settings:

     Field	Required?	Description
     Retriable		Select this checkbox to apply the callout retry rules. The default number of retry attempts is three at intervals of 30 minutes. You can configure the default retry number and intervals. For more information, see Configuring callout settings.

3. (Optional) Add custom callout headers:
   1. In the Additional Settings section, click + Add Custom Callout Header.
   2. Specify the following fields:
      • Header Name: Enter the header name of the custom callout header.
      • Header Value: Enter the header value of the custom callout header.
      You can add merge fields in the header name or header value. For more information, see Add merge fields to a callout template.
   3. Repeat steps a and b to add more custom callout headers.
4. (Optional) Preview the callout request. For more information, see Preview the callout request of a callout template.
5. Click Save.

Add merge fields to a callout template

You can add merge fields to the following places in a callout template:

• Request URL
• Request body
• Custom callout headers

For more information about the merge field syntax, see Merge field syntax for email and callout templates.

To add merge fields when creating or editing a callout template, take the following steps:

1. On the Create Callout Template page, specify the Field Type and Field fields in the Available Merge Fields section.
   Zuora will auto-generate and display the corresponding merge field tag in the Merge Field Tag field. For example, {{DataSource.Account.Id}}.
2. Copy the merge field tag in the Merge Field Tag field.
3. Paste the merge field tag into any of the following places as needed:
   • The Request URL field
   • The Request Body, which must be a JSON-formatted object enclosed with curly braces ({})
   • The Header Name or Header Value field of custom callout headers

Alternatively, you can take the following steps to add merge fields to the request body:

1. On the Create Callout Template page, select the merge fields you want to include in the callout request body from the Merge Fields list in the Request Body section.
   In the Merge Fields list, supported merge fields are categorized by objects associated with the callout template’s related event. If you select an object from the list, all merge fields on this object are selected.
2. Click + Insert Merge Fields.
   Zuora will insert all selected merge fields into the request body. The following is an example:

   {
       "AccountAccountNumber": "{{DataSource.Account.AccountNumber}}",
       "AccountId": "{{DataSource.Account.Id}}"
   }
   

3. (Optional) Customize the key-value pairs in the request body to meet your business requirements.

Callout authentication

Zuora supports the following callout authentication types that help you secure your web service calls:

• Basic and NTLM (NT LAN Manager)
• OAuth 2.0

Callout authentication settings are template-level configurations.

If the Retriable checkbox is selected and callout authentication fails, Zuora will retry the callout notification.

Preview the callout request of a callout template

When creating or editing a callout template, you can assign an object ID that corresponds to the callout template’s related event. Zuora will replace all advanced and data source merge fields in the request URL, request body, and custom callout headers with actual values from the specified object.

For example, if the related event is Account Created, you can assign an account ID, assuming this is the created account. Zuora will replace merge fields from the Account and other associated objects, such as BillToContact and SoldToContact, with actual values from the specified account object.

To preview the callout request, perform the following steps:

1. On the Create Callout Template page, specify an object ID in the Object ID field in the Request Preview section.
   This must be an ID of the object that corresponds to the callout template’s related event. For example, if the related event is Account Created, this must be an account ID. Otherwise, no merge field will be replaced.
   Note that Zuora only replaces advanced and data source merge fields in the request URL, request body, and custom callout headers. You cannot preview merge fields that are not from the base object or associated objects of the callout template. For example, System Health merge fields or system merge fields are not supported for preview.
2. Click Preview.
3. Verify the displayed callout request. The following is an example:
   
4. If the information displayed is not as expected, review and update the configuration of the request URL, request body, or custom callout headers.