Custom payload in alerts integration

  • Release version: Yokohama
  • Updated April 21, 2025
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Custom payload in alerts integration

    Instance Observer integrations in ServiceNow Yokohama release enable you to define and manage custom JSON request payloads for both ServiceNow and third-party alert integrations. This feature allows you to tailor notification payloads by including additional fields, excluding unnecessary data, or formatting them to meet specific third-party API or internal business requirements. This customization removes the need for complex scripted REST APIs on your side.

    Show full answer Show less

    Key Features

    • Default and Custom Payloads: Use a default JSON payload or customize it by modifying keys and values within an editor interface. Changes are previewed live, with validation to ensure JSON correctness.
    • Custom Parameters: Insert custom messages or parameters into the JSON template using existing alert data placeholders. You can add up to 13 custom parameters, with a total of 1 to 20 keys required in the template.
    • Syntax Validation: Built-in syntax validation highlights errors and disables saving until the JSON is valid, ensuring reliable payloads.
    • Third-Party API Compatibility: Modify payload keys and structure to match the expected format of third-party systems, facilitating seamless integration.
    • Actions: Easily revert unsaved changes, reset the payload to default, and test the integration by sending sample notifications to validate webhook behavior.

    Practical Implications for ServiceNow Customers

    This capability empowers you to efficiently customize alert notifications without scripting, streamlining integration with various external systems. You can:

    • Enhance alert payloads with additional contextual information to improve downstream processing and response.
    • Exclude irrelevant data to optimize payload size and meet target system requirements.
    • Adapt payload formats quickly to comply with third-party API specifications, accelerating integration deployment.
    • Validate and test payloads in real-time to ensure accuracy and reduce integration errors.

    Overall, this feature simplifies alert payload customization, reduces development effort, and improves integration reliability.

    Instance Observer integrations allow you to define and manage custom JSON request payload for ServiceNow and third-party integrations.

    You can now include additional fields in notification payloads, exclude specific data that is not required by the target system, format the payload to align with specific third-party API requirements or internal business logic, eliminating the need for complex scripted REST APIs on the customer side.

    • Use either the default payload or customize it to include additional data as needed.
    • Modify the default payload, if needed, which is displayed in the Editor window on the left.
    • Modify either the key or the value, or both as each parameter consists of a key and a value.
    • The Preview section on the right displays the expected JSON payload after rendering.
    • If the JSON is invalid, errors are highlighted, and the option to save is disabled.

    Default mustache payload template

    {
  "alert_number": "{{alert_number}}",
  "alert_type": "{{alert_type}}",
  "alert_name": "{{alert_name}}",
  "alert_time": "{{alert_time}}",
  "instance": "{{instance}}",
  "description": "{{description}}",
  "alert_created": "{{alert_created}}"
}

    Edit payload for default mustache payload template.

    Example: Default Payload + Custom Parameters

    {
"alert_number": "{{alert_number}}",
  "alert_type": "{{alert_type}}",
  "alert_name": "{{alert_name}}",
  "alert_time": "{{alert_time}}",
  "instance": "{{instance}}",
  "description": "{{description}}",
  "alert_created": "{{alert_created}}",
  "Custom_message": "{{alert_name}}' of type {{alert_type}} generated for {{instance}} at {{alert_time}}. Please review.",
  "Severity": “High”
}

    Edit payload for default payload + custom parameters.

    Custom parameters and limits

    The custom_parameter field allows you to insert custom message into the JSON template, you can also use the existing parameters as shown in the custom parameter samples.

    The limitations are:
    • Required: At least one and at most 20 parameters to save the template.
    • Maximum: 13 custom parameters.
    • If exceeded, a warning appears: Template must have at least one default key and up to 20 keys. Adjust or select 'Reset to Default' to apply defaults.

    Samples of custom parameters for syntax reference

    "Information": "An alert {{alert_name}} has been triggered for {{instance}} at {{alert_time}} Description: {{description}}"

    "Alert_message": "New alert '{{alert_name}}' of type {{alert_type}} generated for {{instance}} at {{alert_time}}. Please review."

    "Event_type": "Severity-High! An alert {{alert_name}} has been triggered for {{instance}} at {{alert_time}} Description: {{description}}"

    Third-party request body mapping

    Some third-party integrations require specific key names. You can modify the default payload to match their expected format.

    Example: Third-party request body:
    {
  "endTime": 1,
  "entitySelector": "string",
  "eventType": "AVAILABILITY_EVENT",
  "properties": {},
  "startTime": 1,
  "timeout": 1,
  "title": "string"
}

    Modified IO payload to match third-party format

    Modified IO payload to match third-party format.

    Actions and validation

    Revert Changes
    Restores the last saved content.
    Reset to Default
    Resets the template to its default payload.
    Syntax Validator
    Ensures JSON validity before saving. Errors prevent saving.
    Test Integration
    Sends a sample notification to verify webhook integration.