# Incoming Webhooks

## How incoming webhooks work

This guide explains how to set up incoming webhooks for your integration. The process involves the following steps:

1. **Creating a Flow**: A user creates a new flow in FlowMate using the Integration Center or Integration Portal. Each flow is assigned a unique ID, such as `1234`.
2. **Retrieving Flow ID**: As a FlowMate Partner, retrieve all active flows via the API to get the flow IDs associated with the users who have activated a flow.
3. **Matching Flows to Users:** Next, you will need to match each active flow to a user within your system. \*\*\*\*
4. **Configuring the Webhook**: Now that you know the user's identity, you can configure a webhook for them within your system to send data to their flow at `https://api.platform.openintegrationhub.com/webhooks/{flowId}`
5. **Executing Webhooks**: Any valid requests sent to the flow’s webhook URL will now cause the flow to execute with the payload in the request.

## Setting up incoming webhooks

### Retrieve all active flows

To retrieve the active flows for your users, perform a GET request to the endpoint:

`GET` `https://api.platform.openintegrationhub.com/flows`

**Query Params**

| Parameter        | Type    | Description                                                                                        |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `page[size]`     | integer | Amount of flows per page returned. Default is 10.                                                  |
| `page[number]`   | integer | Number of the page to be returned. Default is 1.                                                   |
| `filter[status]` | string  | Filter results by flow status. Accepts either string ('active' and 'inactive') or integer (1 or 0) |

The response will include a list of flows, each associated with a flow id and a user id. For example:

```json
{
    "data": [
    .....
        {
            "id": "6762e154616e91cb8d8b1aaf",
            "owners": [
                {
                    "id": "636d0762bd257a7eb2373d6c",
                    "type": "user"
                },
                {
                    "id": "636d0762bd257a7eb2373d6a",
                    "type": "tenant"
                }
            ]
        }
    ]
}
```

* **Flow ID**: The `id` field (e.g., `6762e154616e91cb8d8b1aaf`) at the top level of each flow object.
* **User ID**: The `id` field in the `owners` array where `type` is `user` (e.g., `636d0762bd257a7eb2373d6c`).

Use these values to identify the flow and its associated user.

## Retrieve Username Associated with Flow

The user ID from the previous response is the internal ID used by FlowMate and may differ from the user ID your system recognizes. To retrieve the username (which corresponds to the user ID in your system), perform a GET request to the endpoint:

`GET` `https://api.platform.openintegrationhub.com/users/`

The response will include the user's details, such as:

**Response:**

```json
{
    "_id": "636d0762bd257a7eb2373d6c",
    "username": "your-userId",
    "status": "ACTIVE",
    "confirmed": true,
    "canLogin": false,
    "tenant": "61233456678764",
    "roles": [],
    "permissions": [
        "flows.read",
        "tenant.flows.update",
        "flows.update",
        "flows.delete",
        "flows.control",
        "icenter.read",
        "icenter.write",
        "secrets.create",
        "secrets.read",
        "secrets.delete",
        "templates.read",
        "components.read",
        "components.write"
    ],
    "createdAt": "2023-11-09T20:46:58.652Z",
    "updatedAt": "2023-11-09T20:46:58.652Z",
    "__v": 0,
    "safeguard": {
        "failedLoginAttempts": 0,
        "lastLogin": "2024-12-30T13:30:27.529Z"
    }
}
```

## Configure Webhook to FlowMate

Within your system’s webhook functionality, create and configure a webhook to send relevant data as a POST request to the webhook url using the user’s flow ID:

`POST` `https://api.platform.openintegrationhub.com/webhooks/{flowId}`

You can send payload data via POST request using JSON in the request body, which will then be processed in the flow.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://flowmate.gitbook.io/flowmate-documentation/webhooks/incoming-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.