Webhooks

A user can define webhooks which will send POST requests to the specified URL when certain conditions are met.

Defining Webhooks

Webhooks are defined at the workflow level. All hooks take a HookParameters field which includes the URL and header that should be used in the POST request.

pydantic model linq.hooks.HookParameters

Show JSON schema

{
   "title": "HookParameters",
   "type": "object",
   "properties": {
      "url": {
         "title": "Url",
         "type": "string"
      },
      "headers": {
         "additionalProperties": {
            "type": "string"
         },
         "description": "HTTP headers to include in the request",
         "title": "Headers",
         "type": "object"
      }
   },
   "required": [
      "url"
   ]
}

Fields:

headers (dict[str, str])
url (str)

field url: str [Required]

field headers: dict[str, str] [Optional]: HTTP headers to include in the request

to_api_input() → HookParametersInput

classmethod from_api_output(api_output_parameters: HookParameters) → Self

Currently, users may define the following hooks:

RunStateChangeHook
TaskStateChangeHook
SafetyStateChangeHook
LabwareMovementHook
NewPlanHook

For example:

my_state_hook = RunStateChangeHook(
    parameters=HookParameters(
        url="https://example.com/foo",
        headers={
            "X-My-Header": "my-header-val",
        },
)

RunStateChangeHook will send a POST request when the run changes state.

class linq.hooks.RunStateChangeHook(*, parameters: HookParameters, filter: Literal[Filters.ON_RUN_STATE_CHANGE] = FieldInfo(annotation=NoneType, required=True, description='Event type triggering the hook. No longer required.', deprecated=True))

Hook to be triggered when a run state changes.

Example response:

{
  "state": "paused",
  "message": "The run is paused.",
  "run_id": "00000000-0000-0000-000000000000",
  "timestamp": "2025-04-17T09:30:00.000Z"
}

Possible states: “started”, “paused”, “resumed” and “stoped”.

TaskStateChangeHook requires a task ID. A POST request will be sent when the specified task enters a new state.

class linq.hooks.TaskStateChangeHook(*, parameters: HookParameters, filter: Literal[Filters.ON_TASK_STATE_CHANGE] = FieldInfo(annotation=NoneType, required=True, description='Event type triggering the hook. No longer required.', deprecated=True), task_ids: list[str] = FieldInfo(annotation=NoneType, required=True, description='List of task IDs that the hook should be triggered for. If empty, the hook will be triggered for all tasks.'))

Hook to be triggered when a task state changes.

Example response:

{
  "task_id": "run_action_1",
  "instrument_id": "instrument_1",
  "state": "succeeded",
  "action": "run",
  "error": "",
  "run_id": "00000000-0000-0000-000000000000",
  "timestamp": "2025-04-17T09:30:00.000Z"
}

Possible states: “started”, “failed” and “succeeded”.

SafetyStateChangeHook will send a POST request when the safety state changes.

class linq.hooks.SafetyStateChangeHook(*, parameters: HookParameters, filter: Literal[Filters.ON_SAFETY_STATE_CHANGE] = FieldInfo(annotation=NoneType, required=True, description='Event type triggering the hook. No longer required.', deprecated=True))

Hook to be triggered on changes to the state of the safety adapter.

Example response:

{
  "state": "emergency_stop",
  "run_id": "00000000-0000-0000-000000000000",
  "timestamp": "2025-04-17T09:30:00.000Z"
}

Possible states: “emergency_stop”, “functional_stop” and “reset”.

LabwareMovementHook requires labware IDs (for specific labware items, otherwise leave blank for all labware) and a trigger field to be set (start, end or both). A POST request will be sent when the selected trigger event occurs.

class linq.hooks.LabwareMovementHook(*, parameters: HookParameters, filter: Literal[Filters.ON_LABWARE_MOVEMENT] = FieldInfo(annotation=NoneType, required=True, description='Event type triggering the hook. No longer required.', deprecated=True), labware_ids: list[str] = FieldInfo(annotation=NoneType, required=True, description='List of labware IDs that the hook should be triggered for. If empty, the hook will be triggered for all labware.'), trigger_on: Literal['start', 'end', 'both'] = FieldInfo(annotation=NoneType, required=False, default='both', title='Trigger On', description="When to trigger the hook. 'start' triggers the hook when the labware is picked up, 'end' triggers the hook when the labware is placed down, 'both' does both."))

Hook to be triggered when labware is transported.

Example response:

{
  "labware_id": "plate_1",
  "state": "started",
  "source_instrument_id": "inst_A1",
  "destination_instrument_id": "inst_B2",
  "source_slot": 1,
  "destination_slot": 2,
  "run_id": "00000000-0000-0000-000000000000",
  "timestamp": "2025-04-17T09:30:00.000Z"
}

Possible states: “started”, “finished” and “failed”.

NewPlanHook will send a POST request when a new plan is created.

class linq.hooks.NewPlanHook(*, parameters: HookParameters, filter: Literal[Filters.ON_NEW_PLAN] = FieldInfo(annotation=NoneType, required=True, description='Event type triggering the hook. No longer required.', deprecated=True))

Hook to be triggered when a new plan is generated.

Example response:

{
  "remaining_worktime": 480,
  "run_id": "00000000-0000-0000-000000000000",
  "timestamp": "2025-04-17T09:30:00.000Z"
}

The remaining worktime is defined as how much longer (in seconds) the run is expected to take based on the new plan.