Triggering Actions via API

Custom Actions Trigger API

OpsLevel’s GraphQL API lets you list available triggers for Custom Actions, invoke them programmatically, and poll their status.

1. List Trigger Definitions

Fetch all Custom Action trigger definitions available in your account.

query GetCustomActionsTriggerDefinitions {
  account {
    customActionsTriggerDefinitions {
      totalCount             # Total number of trigger definitions
      nodes {
        __typename           # GraphQL type name (CustomActionsTriggerDefinition)
        id                   # Globally-unique ID for the trigger
        name                 # Human-readable name
        entityType           # Entity the trigger applies to (e.g. "Service")
      }
    }
  }
}

Response fields:

`Field`	`Type`	Description
`totalCount`	`Int`	Count of trigger definitions
`nodes[].__typename`	`String`	GraphQL type (always `CustomActionsTriggerDefinition`)
`nodes[].id`	`ID`	Trigger definition ID
`nodes[].name`	`String`	Trigger definition name
`nodes[].entityType`	`String`	Entity type (e.g. `Service`, `Account`)

2. Invoke a Trigger

Invoke a Custom Action by its trigger definition ID. You can optionally pass a targetObject (e.g. a Service ID) and a JSON‐encoded manualInputs object.

mutation InvokeCustomAction(
  $triggerDefinitionId: ID!
  $targetObject: IdentifierInput
  $manualInputs: JSON
) {
  customActionsTriggerInvoke(
    input: {
      triggerDefinition: { id: $triggerDefinitionId }
      targetObject: $targetObject
      manualInputs: $manualInputs
    }
  ) {
    triggerEvent {
      ...TriggerEventFragment
      __typename
    }
    errors {
      message
      path
      __typename
    }
    __typename
  }
}

fragment TriggerEventFragment on CustomActionsTriggerEvent {
  id                      # ID of the created trigger event
  status                  # Current status: PENDING, PENDING_APPROVAL, SUCCESS, FAILURE
  definition {
    name                  # Name of the trigger definition
    owner {
      id
      name
      href
      __typename
    }
    __typename
  }
}

Input Arguments

`Variable`	`Type`	Description
`triggerDefinitionId`	`ID!`	ID of the trigger definition to invoke
`targetObject`	`IdentifierInput`	(Optional) ID of the resource to associate in the form `{id: Z2lkOi8vb3BzbG...."}` (e.g. a Service)
`manualInputs`	`JSON`	(Optional) Key/value map of inputs defined in your action’s manual‐inputs schema

Payload

`Field`	`Type`	Description
`triggerEvent`	`CustomActionsTriggerEvent`	Newly created event; see `TriggerEventFragment`
`errors[]`	`{ message, path, __typename }`	Validation or execution errors encountered when enqueueing the action trigger

3. Poll Trigger Event Status

After invoking, you can poll the event to check progress or final outcome:

query GetCustomActionTriggerEvent($eventId: ID!) {
  account {
    customActionsTriggerEvent(id: $eventId) {
      id        # Event ID
      status    # One of: PENDING, PENDING_APPROVAL, SUCCESS, FAILURE
    }
  }
}

Input Arguments

`Variable`	`Type`	Description
`eventId`	`ID!`	ID returned in `triggerEvent.id`

Response

`Field`	`Type`	Description
`id`	`ID`	The trigger event’s unique identifier
`status`	`String`	Current status (e.g. `SUCCESS`, `FAILURE`)

Status Workflow

PENDING: The trigger has been accepted.
PENDING_APPROVAL: The action is waiting for an approval before it executes.
SUCCESS: Webhook returned a 2xx status.
FAILURE: Non-2xx response or execution failure.

Use the id from the invocation response to poll until you reach SUCCESS or FAILURE.

Read more about configuring manual inputs → Manual Inputs Guide

Action Permissions

API tokens can run any custom action you have created because they are considered to be Administrators

User unavailable in Action Context

You cannot use the user object in liquid templates that are part of an action you invoke via API.

If you require information about a user that has triggered an action via API, you can include it as part of a Manual Input