Validating workflow trigger data

Workflow trigger data is critical for ensuring your notifications have the right content and context. To help prevent errors and maintain data integrity, Knock offers a trigger data validation feature that allows you to specify the expected structure of the data passed to your workflows.

Trigger data validation lets you define a JSON schema that describes the expected shape and types of data passed to your workflow. If the incoming data doesn't match the specified schema, the trigger endpoint will return a 422 Unprocessable Entity error with details about where the validation failed.

How to set up trigger data validation

You can enable and configure trigger data validation in two ways:

1. Via the Workflow Builder:

   • Navigate to the "Trigger step" in the workflow builder
   • Under the "API params" section, click "Edit schema"
   • Supply a valid JSON schema
   • Commit your changes for the schema to take effect

2. Via the Management API or CLI:

   • Use the trigger_data_json_schema field to provide your schema

Example schema

Here's an example of a simple schema that expects a name property in the trigger data:

With this schema in place, if the name property is missing or not a string, the trigger endpoint will return a 422 error.

Error handling

When the incoming data fails validation, the API will respond with:

• Status code: 422 Unprocessable Entity
• Response body: A list of validation errors, indicating where the data failed to meet the schema requirements

This ensures that your workflows are not executed with incorrect or incomplete data, helping to maintain the integrity of your notification system.

Availability

Trigger data validation is available to all Knock customers. We recommend implementing it for all critical workflows to ensure data consistency and prevent potential issues in your notification pipeline.