Alert Webhooks

Alert request bodies

{
  "unit21_id": 11532778,
  "change": "CREATED",
  "alert_id": null,
  "alert_type": "manual",
  "object_type": "ALERT",
  "status": "OPEN",
  "disposition": "UNRESOLVED",
  "title": "Test",
  "description": "Test of webhooks",
  "changed_by": null,
  "change_time": 1661957674,
  "start_date": null,
  "end_date": null,
  "entities": [
    {
      "entity_id": "u-65b0bfa0-fe19-4e91-9225-c8174c7cc6d8",
      "entity_type": "user",
      "resolution": "UNRESOLVED"
    }
  ],
  "events": [
    {
      "event_id": "t-a57137d8-7387-4517-8f11-d2a7aa842180",
      "event_type": "transaction",
      "resolution": "UNRESOLVED"
    }
  ],
  "instruments": [],
  "triggered_by_rules": [],
  "assigned_to": null,
  "tags": [
    "account_type:market24"
  ],
  "custom_data": {}
}

For the webhook CREATED, REOPENED, and CLOSED, the following fields are sent:

Field NameValue TypeDetails
unit21_idNumberA Unit21 internally-assigned unique identifier for the alert within our system
changeStringCLOSED, REOPENED or CREATED
alert_idStringA Unit21 identifier for the alert
alert_typeStringA string representing the type of alert
object_typeStringALERT
statusStringOne of OPEN or CLOSED
dispositionStringA state that represents either the alert's resolution or a designation for further actions. This field can be defined by an action trigger button, where each action trigger corresponds to one disposition
titleStringTitle assigned to the alert
descriptionStringA high level descriptive phrase about the alert
changed_byStringEmail address of the agent that triggered the status change (if applicable)
change_timeNumberTime the change was triggered in Epoch time format (number of seconds elapsed since 1 Jan 1970 00:00:00 UTC)
start_dateNumberStart datetime of the events or entities encapsulated by this alert in Epoch time format (number of seconds elapsed since 1 Jan 1970 00:00:00 UTC)
end_dateNumberEnd datetime of the events or entities encapsulated by this alert in Epoch time format (number of seconds elapsed since 1 Jan 1970 00:00:00 UTC)
entitiesObject[]An object list of entities flagged by the rule. Each object contains an ID, the entity type (user or business), a non-Unit21 identifier, and a resolution
eventsObject[]An object list of events flagged by the rule. Each object contains an ID, the event type (transaction or action), a non-Unit21 identifier, and a resolution
instrumentsObject[]An object list of instruments flagged by the rule. Each object contains an ID, the instrument type, a non-Unit21 identifier, and a resolution
triggered_by_rulesObject[]A list of rule object(s) that triggered this alert, each consisting of a Unit21 ID and a non-Unit21 identifier for the rule
assigned_toStringEmail address of the agent that the alert was assigned to at the time of the status change
tagsString[]A list of tags that are associated with this alert, always of the format key:value
custom_dataObjectAny custom information that you wish our system to associate with this alert (accepts any valid JSON object)
{
  "unit21_id": 11532778,
  "change": "ACTION_TRIGGERED",
  "alert_id": null,
  "alert_type": "manual",
  "object_type": "ALERT",
  "status": "OPEN",
  "disposition": "UNRESOLVED",
  "title": "Test",
  "description": "Test of webhooks",
  "changed_by": "[email protected]",
  "change_time": 1661957711,
  "start_date": null,
  "end_date": null,
  "entities": [
    {
      "entity_id": "u-65b0bfa0-fe19-4e91-9225-c8174c7cc6d8",
      "entity_type": "user",
      "resolution": "UNRESOLVED"
    }
  ],
  "events": [
    {
      "event_id": "t-a57137d8-7387-4517-8f11-d2a7aa842180",
      "event_type": "transaction",
      "resolution": "UNRESOLVED"
    }
  ],
  "instruments": [],
  "triggered_by_rules": [],
  "assigned_to": null,
  "tags": [
    "account_type:market24",
    "alert_type:high_priority"
  ],
  "custom_data": {},
  "action_trigger_external_id": null,
  "subdisposition": [],
  "disposition_notes": null
}

For the webhook ACTION_TRIGGERED, the following fields are sent in addition to the ones above:

Field NameValue TypeDetails
subdispositionListList of key-value pairs. A sub-state that represents either the alert's resolution or a designation for further actions. This field can be be defined by an action trigger button, where each action trigger allows for agents to dynamically select a subdisposition during alert investigation from a list of predefined values in the action trigger configuration process
disposition_notesStringA free text field that contains agent-entered elaborations on the alert's disposition. A non-empty value may be required by the action trigger depending on the action trigger configuration
action_trigger_external_idStringA unique identifier defined at button create time
{}

For the webhook GENERATION_HIT_LIMIT, the following fields are sent:

Field NameValue TypeDetails
unit21_idNumberA Unit21 internally-assigned unique identifier for the alert within our system
rule_idStringA Unit21 identifier for the rule
statusStringOne of OPEN or CLOSED
dispositionStringA state that represents either the alert's resolution or a designation for further actions. This field can be defined by an action trigger button, where each action trigger corresponds to one disposition
object_typeStringRULE
changeStringALERT_GENERATION_LIMITED
changed_byStringEmail address of the agent that triggered the status change (if applicable)
titleStringTitle assigned to the alert
descriptionStringA high level descriptive phrase about the alert
change_timeNumberTime the change was triggered in Epoch time format (number of seconds elapsed since 1 Jan 1970 00:00:00 UTC)
start_dateNumberStart datetime of the events or entities encapsulated by this alert in Epoch time format (number of seconds elapsed since 1 Jan 1970 00:00:00 UTC)
end_dateNumberEnd datetime of the events or entities encapsulated by this alert in Epoch time format (number of seconds elapsed since 1 Jan 1970 00:00:00 UTC)
entitiesObject[]An object list of entities flagged by the rule. Each object contains an ID, the entity type (user or business), a non-Unit21 identifier, and a resolution
eventsObject[]An object list of events flagged by the rule. Each object contains an ID, the event type (transaction or action), a non-Unit21 identifier, and a resolution
tagsString[]A list of tags that are associated with this alert, always of the format key:value
instrumentsObject[]An object list of instruments flagged by the rule. Each object contains an ID, the instrument type, a non-Unit21 identifier, and a resolution
created_byStringEmail address of the agent that generated the limit
watchersArray[]List of agent emails
{}

For the webhook COMPONENT_ACTION_TRIGGERED, the following fields are sent:

Field NameValue TypeDetails
action_trigger_external_idStringA unique identifier defined at button create time
change_timeNumberTime the change was triggered in Epoch time format (number of seconds elapsed since 1 Jan 1970 00:00:00 UTC)
changed_byStringEmail address of the agent that triggered the status change (if applicable)
unit21_idNumberA Unit21 internally-assigned unique identifier for the alert within our system
alert_idStringA identifier for the alert, this will be null unless the alert was created via the API
alert_typeStringA string representing the type of alert
object_typeStringALERT
changeStringALERT_COMPONENT_ACTION
changed_eventsObject[]An object list of events changed by the current action. This does not include all events in the alert, only the events that were actively changed. Each object contains a Unit21 ID, the event type (transaction or action), a non-Unit21 identifier, and a resolution well. The resolution is configured on a per button/action basis
changed_entitiesObject[]An object list of entities changed by the current action. This does not include all entities in the alert, only the entities that were actively changed. Each object contains a Unit21 ID, the entity type (user or business), a non-Unit21 identifier, and a resolution. The resolution is configured on a per button/action basis
changed_instrumentsObject[]An object list of instruments changed by the current action. This does not include all instruments in the alert, only the instruments that were actively changed. Each object contains a Unit21 ID, the instrument type, a non-Unit21 identifier, and a resolution. The resolution is configured on a per button/action basis
tagsString[]A list of tags that are associated with this alert, always of the format key:value