Creating a workflow

Learn how to utilize the Workflow API to create custom workflows.

To create a new workflow, you must make a POST request to with a JSON payload that defines that workflow. If you're using our Terraform provider, the provider takes care of this operation for you. The payload consists of three keys: name, controls, and conditions. A full example:

  "name": "provision-database", 
  "conditions": [
     "field": "service",
     "value": "database-service",
     "operator": "eq"
  "controls": {
    "authentication": true, 
    "reason": true, 
    "approval": {
      "count": 1, 
      "self_approval": true, 
      "duration": 1, 
      "timeout": 30, 
      "responders": {
        "admins": "required",
        "[email protected]": "optional"
      "sources": {
        "email": true,
        "slack": {
          "channel": "#database-ops",
          "fields": ["command", "reason"]
      "oncalls": {
        "pagerduty": "Default",
  • name Required

    • The string name of this workflow. Cannot contain spaces.
  • controls Required

    • An object that details the requirements and logic that make up this workflow.
    • Object keys:
      • authentication
        • boolean
        • Whether or not the user must be authenticated when submitting an event.
      • reason
        • boolean
        • Whether or not a reason for approval request is required when submitting an event.
      • approval
        • object
        • Detailed settings for the approval workflow.
        • Object keys:
          • count
            • integer
            • The number of individual approvals (i.e. approvals by different people) required for an event to be approved.
            • Default: 1
          • self_approval
            • boolean
            • Whether or not the requestor for this approval request can approve their own action.
            • Default: false
          • duration
            • integer, representing minutes
            • After an event in this workflow is approved, auto-approve subsequent events with the same id.
            • Default: 0
            • Experimental
          • timeout
            • integer, representing minutes
            • How long an approval request is valid before it will timeout.
            • Default: 10
          • responders
            • object of objects
            • What groups or user can respond (i.e. approve) this action. Any number of key/value pairs can be given.
            • Each key in the object should be either:
              • A group name representing a group, e.g., admins
              • A group id representing a group, e.g., group_1s8bso0Mr80MHli6fBb9QfZ5POr
              • An email address associated with a Cased user, e.g., [email protected]
              • A user ID representing a user, e.g. user_1s8bsqKiRoTxWe8hQmsq2LFF74Q
            • Each value should be strings of either:
              • required indicating that this group/user must approve the request.
              • optional indicating that this group/user can approve the request.
          • sources
            • object
            • Represents the mechanisms that can be used to approve requests.
            • Valid keys are strings, and include:
              • email
                • Set the value to true to enable email approval.
              • slack
                • The value for this is an object of form:
                    "channel": "#your-channel-name",
                    "fields": ["ip", "command", "reason"]
              • Object keys:
                • fields (Optional)
                  • The metadata you would like to see in a slack approval request notification.
                  • If not supplied, all metadata will show in the message.
          • oncalls
            • object
            • Represents the mechanisms that can be used to auto-approve requests when requester is oncall.
            • Valid keys are strings, and include:
              • pagerduty
                • Set the value to your pagerduty escalation policy name.
  • conditions Optional

    • An array of structured conditions that determine whether or not this workflow is activated.

    • Each array object should be of form:

        "field": "service",
        "value": "my-service-name",
        "operator": "eq"
    • In this example, if an event is sent to the /workflows/events route with field called service, and the value of that field is my-service-name, then this workflow will be executed.

    • Valid operators include:

      • eq for equivalence (not case-sensitive)
      • not for non-equivalence (not case-sensitive)
      • Future fields with include regular expression matchers.

Questions? Contact us.

Did this page help you?