Resthook integration

Guideflow allows Guideflow users to create hooks to be notified about events.

Each flow can have multiple hooks, each for a specific event. You can create, list, and delete hooks.

Hooks management API

To use Hooks API, you must generate an API key in your Guideflow account. You can do it in Settings -> API Keys Section of your workspace.

Pass your API key in Api-Authorization header.

{
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Api-Authorization': api_key
}

Create hook

POST https://app.guideflow.com/v1/user/hooks

Body

{
  flowId: number,
  event: "first-interaction" | "lead-created" | "slide-viewed" | "external-link-clicked" | "completed" | "end-session",
  targetUrl: string
}

Response

{
  "id": 53,
  "workspaceId": 2,
  "createdAt": "2024-01-15T10:01:19.729Z",
  "flowId": 10,
  "event": "end-session",
  "targetUrl": "https://google.com",
  "status": "Enable",
  "lastHttpStatus": null,
  "lastHttpError": null,
  "lastHttpCallDate": null
}

Where targetUrl is the url where you want to receive events, event is the name of the event you want to subscribe to and flowId is the id of the flow you want to subscribe to.

List hooks

GET https://app.guideflow.com/v1/hooks

Response

[
  {
    "id": 53,
    "workspaceId": 2,
    "createdAt": "2024-01-15T10:01:19.729Z",
    "flowId": 10,
    "event": "end-session",
    "targetUrl": "https://google.com",
    "status": "Enable",
    "lastHttpStatus": null,
    "lastHttpError": null,
    "lastHttpCallDate": null
  },
  ...
]

Delete hook

DELETE https://app.guideflow.com/v1/hooks/:id

Response

{
  "count": 1
}

Getting list of Guideflows

GET https://app.guideflow.com/v1/flow/byWorkspace

Pass your API key in Api-Authorization header.

{
  'Accept': 'application/json',
  'Api-Authorization': api_key
}

Response

[
  {
    "workspaceId": 2,
    "id": 10,
    "name": "New guideflow"
  },
  ...
]

---

List of supported events

first-interaction Triggers when a user opens a guideflow in the player.

Schema

{
  "guideflow_session_id": string,
  "guideflow_cta_clicked": string<boolean>,
  "guideflow_steps_total_number": string<number>,
  "guideflow_percent_of_completion": string,
  "guideflow_time_spend": string,
  "guideflow_is_completed": string<boolean>,
  "guideflow_workspace_id": string<number>,
  "guideflow_folder_id": string<number>,
  "guideflow_id": string<number>,
  "guideflow_name": string,
  "guideflow_step_id": string<number>,
  "guideflow_step_index": string<number>,
  "guideflow_source": "embed" |  "player" |  "customLink" | "publicPage" | "preview",
  "variables": Object<string, string>
}

Example

{
  "guideflow_session_id": "f3f35989-8f9c-4f55-8c7e-a4cd481da53d",
  "guideflow_cta_clicked": "false",
  "guideflow_steps_total_number": "6",
  "guideflow_percent_of_completion": "0",
  "guideflow_time_spend": "0s",
  "guideflow_is_completed": "false",
  "guideflow_workspace_id": "2",
  "guideflow_folder_id": "7",
  "guideflow_id": "10",
  "guideflow_name": "New guideflow",
  "guideflow_step_id": "0",
  "guideflow_step_index": "0",
  "variables": {
    "customVariableFromQueryString": "value"
  }
}

lead-created Triggers when a user fills in the form or uses a custom link with pre-defined variables.

Schema

{
  "guideflow_session_id": string,
  "guideflow_cta_clicked": string<boolean>,
  "guideflow_steps_total_number": string<number>,
  "guideflow_percent_of_completion": string,
  "guideflow_time_spend": string,
  "guideflow_is_completed": string<boolean>,
  "guideflow_url": string,
  "guideflow_workspace_id": string<number>,
  "guideflow_folder_id": string<number>,
  "guideflow_folder_name": string,
  "guideflow_id": string<number>,
  "guideflow_name": string,
  "guideflow_step_id": string<number>,
  "guideflow_step_index": string<number>,
  "guideflow_step_name": string,
  "variables": Object<string, string>
}

Example

{
  "guideflow_session_id": "afa3b61f-e78b-4259-819d-7c1da7eab90e",
  "guideflow_cta_clicked": "false",
  "guideflow_steps_total_number": "6",
  "guideflow_percent_of_completion": "0",
  "guideflow_time_spend": "1 m, 41.9 s",
  "guideflow_is_completed": "false",
  "guideflow_url": "http://app.guideflow.com/player/oyv1dulvd0?customVar=value&first_name=John",
  "guideflow_workspace_id": "2",
  "guideflow_folder_id": "7",
  "guideflow_folder_name": "Folder",
  "guideflow_id": "10",
  "guideflow_name": "New guideflow",
  "guideflow_step_id": "131",
  "guideflow_step_index": "1",
  "guideflow_step_name": "Step",
  "variables": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "company": "Google",
    "phone": "[phone]",
    "website": "https://google.com",
    "text": "short",
    "textarea": "long",
    "date": "2024-01-12"
  }
}

slide-viewed Triggers when the user has viewed a step inside a guideflow.

Schema

{
  "guideflow_session_id": string,
  "guideflow_time_spend": string,
  "guideflow_id": string<number>,
  "guideflow_step_id": string,
  "guideflow_step_index": string<number>,
  "guideflow_step_name": string
}

Example

{
  "guideflow_session_id": "220e6b6a-5f86-4460-ae89-abd01d1834c7",
  "guideflow_time_spend": "2 m, 27.1 s",
  "guideflow_id": "10",
  "guideflow_step_id": "150",
  "guideflow_step_index": "3",
  "guideflow_step_name": "Popup"
}

external-link-clicked Triggers when a user clicks an external link, usually at the final popup.

Schema

{
  "guideflow_id": string<number>,
  "guideflow_session_id": string,
  "guideflow_cta_clicked": string,
  "guideflow_cta_clicked_location": "end_popup" | "start_popup" | "slide_popup"
}

Example

{
  "guideflow_id": "10",
  "guideflow_session_id": "220e6b6a-5f86-4460-ae89-abd01d1834c7",
  "guideflow_cta_clicked": "https://google.com",
  "guideflow_cta_clicked_location": "end_popup"
}

completed Triggers when the user has reached the end of a guideflow.

Schema

{
  "guideflow_id": string<number>,
  "guideflow_session_id": string,
  "guideflow_is_completed": string<boolean>,
  "guideflow_percent_of_completion": string
}

Example

{
  "guideflow_id": "10",
  "guideflow_session_id": "220e6b6a-5f86-4460-ae89-abd01d1834c7",
  "guideflow_is_completed": "true",
  "guideflow_percent_of_completion": "100"
}

end-session Triggers when the user closes or leaves a guideflow (i.e., closes page).

Schema

{
  "guideflow_session_id": string,
  "guideflow_user_hash": string,
  "guideflow_user_id": string<number> | null,
  "guideflow_id": string<number>,
  "data": {
    "variables": Object<string, string>,
    "externalLinksClicked": Array<
      {
        "url": string,
        "location": "end_popup" | "start_popup" | "slide_popup"
      }
    >,
    "totalSpentTime": string,
    "percentOfCompletion": string<number>,
    "os": {
      "name": string,
      "version": string
    }
  }
}

Example

{
  "guideflow_session_id": "220e6b6a-5f86-4460-ae89-abd01d1834c7",
  "guideflow_user_hash": "9449cb75-08a9-4191-8acc-dfa0bb4272e5",
  "guideflow_user_id": '',
  "guideflow_id": "10",
  "data": {
    "variables": {
      "first_name": "Alex",
      "customQueryStringVariable": "value"
    },
    "externalLinksClicked": [
      {
        "url": "https://google.com",
        "location": "end_popup"
      }
    ],
    "totalSpentTime": "14.6 s",
    "percentOfCompletion": "100",
    "os": {
      "name": "Mac OS",
      "version": "10.15.7"
    }
  }
}