Sending an event/approval request

Learn how to send an event/approval request using the Workflows API.

Basics

An event can trigger an approval workflow. Events are JSON objects of arbitrary keys and scalar values like this.

{
  "command": "database-up",
  "organization": "AcmeCo",
  "url": "https://example.com/database",
  "database_size": 500000,
  "iops": 5000,
    "ip": "56.11.20.203",
}

They are generally sent from applications that want to make use of Cased's API approval workflow engine. Include as much data in the event as you think will be useful for a person approving the action.

To send an event in general, send a POST request from your application with a JSON body to api.cased.com/workflows/events. If the event includes a key/value pair that matches a condition (see above), then the first matching workflow will be executed.

For an event to be always executed by a specific workflow, send a POST request from your application with a JSON body to api.cased.com/workflows/{your-workflow-name}/events. In addition to the workflow name, you can also user the workflow id, e.g., workflow_1s8bso0Mr806fBb9QfZ5POr.

Using exploders

Some special keys that you can send, called exploders, are automatically enhanced with additional data on the Cased side. These keys currently include:

  • command For a command-line operation, we will parse the entry and add the program name, args, and flags as separate fields.
  • url We will add additional data like protocol, host, and port.
  • ip_address We will add additional data about the physical location associated with the IP address.
  • user_agent We will parse the user agent and add, e.g, browser name, version, and operating system.

Return values

The API returns JSON after an event is sent.
If a workflow matches (with conditions) or is specified:

{
  "result": {
    "id": "result_1s7v76TByYnuo7F7PcJTGRdeJpk",
    "state": "unfulfilled",
    "api_url": "https://app.cased.com/api/workflows/events/event_1s7v775aG6rkzh4c1gclPAFYC35/result",
    "controls": {
      "reason": {
        "state": "fulfilled"
      },
      "authentication": {
        "state": "unfulfilled",
        "user": null,
        "url": "https://app.cased.com/g47d0538ad94b3e21280ebcff683ced",
        "api_url": "https://app.cased.com/api/cli/applications/users/identify/g47d0538ad94b3e21280ebcff683ced",
        "code": "g47d0538ad94b3e21280ebcff683ced"
      }
    },
    "workflow": {
      "id": "workflow_1s685mnfoPDarC8IjeBC35w6ufa",
      "name": "database-workflow",
      "conditions": [
        {
          "field": "service",
          "value": "database-service",
          "operator": "eq"
        }
      ]
    }
  },
  "id": "event_1s7v775aG6rkzh4c1gclPAFYC35",
  "api_url": "https://app.cased.com/api/workflows/events/event_1s7v775aG6rkzh4c1gclPAFYC35",
  "event": {
    "command": "/usr/local/bin/database-up iops 30000",
    "service": "databse-service",
    "reason": "Updating database IOPS",
    "command.directory": "/usr/local/bin",
    "command.program": "database-up",
    "command.arguments": ["iops", "3000"],
    "command.flags": []
  },
  "original_event": {
    "command": "/usr/local/bin/database-up iops 30000",
    "service": "database-service",
    "reason": "Updating database IOPS"
  },
  "updated_at": "2021-05-05T17:37:51.959243Z",
  "created_at": "2021-05-05T17:37:51.959243Z"
}

If no workflow matches, the request is considered fulfilled, and some metadata is returned:

{
  "result": {
    "id": "result_1s7uVmFf6acC2aSd59qKJwqRrf6",
    "state": "fulfilled",
    "api_url": "https://cased.com/api/workflows/events/event_1s7uVhSVoAMYplu6V4k7yfRnz8C/result",
    "controls": null,
    "workflow": null
  },
  "id": "event_1s7uVhSVoAMYplu6V4k7yfRnz8C",
  "api_url": "http://cased.com/api/workflows/events/event_1s7uVhSVoAMYplu6V4k7yfRnz8C",
  "event": {
    "command": "/usr/local/bin/terraform plan",
    "service": "cli",
    "reason": "Checking latest test",
    "command.program": "terraform",
    "command.directory": "/usr/local/bin",
    "command.arguments": "plan",
    "command.flags": []
  },
  "original_event": {
    "command": "/usr/local/bin/terraform plan",
    "service": "cli",
    "reason": "Checking latest test"
  },
  "updated_at": "2021-05-05T17:32:54.215243Z",
  "created_at": "2021-05-05T17:32:54.215243Z"
}

Questions? Contact us.
FAQ


Did this page help you?