# 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.

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

**Create hook**

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

Body

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

Response

```js
{
  "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

```js
[
  {
    "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

```js
{
  "count": 1
}
```

**Getting list of Guideflows**

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

Pass your API key in `Api-Authorization` header.

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

Response

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

***

**List of supported events**

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

<details>

<summary>Schema</summary>

```js
{
  "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>
}
```

</details>

<details>

<summary>Example</summary>

```js
{
  "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"
  }
}
```

</details>

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

<details>

<summary>Schema</summary>

```js
{
  "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>
}
```

</details>

<details>

<summary>Example</summary>

```js
{
  "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": "jsmith@google.com",
    "company": "Google",
    "phone": "+1453545645",
    "website": "https://google.com",
    "text": "short",
    "textarea": "long",
    "date": "2024-01-12"
  }
}
```

</details>

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

<details>

<summary>Schema</summary>

```js
{
  "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
}
```

</details>

<details>

<summary>Example</summary>

```js
{
  "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"
}
```

</details>

<br>

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

<details>

<summary>Schema</summary>

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

</details>

<details>

<summary>Example</summary>

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

</details>

<br>

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

<details>

<summary>Schema</summary>

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

</details>

<details>

<summary>Example</summary>

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

</details>

<br>

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

<details>

<summary>Schema</summary>

```js
{
  "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
    }
  }
}
```

</details>

<details>

<summary>Example</summary>

```js
{
  "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"
    }
  }
}
```

</details>