Management API

Webhook API

Formbricks' Webhook API offers a powerful interface for interacting with webhooks. Webhooks allow you to receive real-time HTTP notifications of changes to specific objects in the Formbricks environment.

The behavior of the webhooks is determined by their trigger settings. The trigger determines which updates the webhook sends. Current available triggers include "responseCreated", "responseUpdated", and "responseFinished". This allows you to customize your webhooks to only send notifications for the events that are relevant to your application.

Webhooks are tied to a specific Formbricks environment. Once set, a webhook will receive updates from all surveys within this environment. This makes it easy to manage your data flow and ensure that all relevant updates are caught by the webhook.

This set of API can be used to

List All Webhooks
Get Webhook
Create Webhook
Delete Webhook

And the detailed Webhook Payload is elaborated here.

These APIs are designed to facilitate seamless integration of Formbricks with third-party systems. By making use of our webhook API, you can automate the process of sending data to these systems whenever significant events occur within your Formbricks environment.

You will need an API Key to interact with these APIs.

GET/api/v1/webhooks

List Webhooks

Learn how to retrieve a list of all webhooks via API.

Mandatory Headers

Name
x-Api-Key
Type
string
Description
Your Formbricks API key.

Request

GET

/api/v1/webhooks

curl --location \
'https://app.feedbackflowhq.com/api/v1/webhooks' \
--header \
'x-api-key: <your-api-key>'

Response

{
  "data": [
    {
      "id": "cliu1kdza000219zftad4ip6c",
      "createdAt": "2023-06-13T08:49:04.198Z",
      "updatedAt": "2023-06-13T08:49:04.198Z",
      "url": "https://mysystem.com/myendpoint",
      "environmentId": "clisypjy4000319t4imm289uo",
      "triggers": [
        "responseFinished"
      ]
    }
  ]
}

GET/api/v1/webhooks/<webhook-id>

Retrieve Webhook by ID

Mandatory Headers

Name
x-Api-Key
Type
string
Description
Your Formbricks API key.

Request

GET

/api/v1/webhooks/<webhook-id>

curl --location \
'https://app.feedbackflowhq.com/api/v1/webhooks/<webhook-id>' \
--header \
'x-api-key: <your-api-key>'

Response

{
  "data": {
    "id": "cliu167rk000019zfhbo68bar",
    "createdAt": "2023-06-13T08:38:02.960Z",
    "updatedAt": "2023-06-13T08:38:02.960Z",
    "url": "https://mysystem.com/myendpoint",
    "environmentId": "clisypjy4000319t4imm289uo",
    "triggers": [
      "responseFinished"
    ]
  }
}

POST/api/v1/webhooks

Create Webhook

Add a webhook to your product.

Mandatory Headers

Name
x-Api-Key
Type
string
Description
Your Formbricks API key.

Request Body Parameters

Name
url
Type
string
Description
The URL where the webhook will send data to.
Name
triggers
Type
string[]
Description
List of events that will trigger the webhook.
Name
surveyIds
Type
string[]
Description
List of survey IDs that will trigger the webhook. If not provided, the webhook will be triggered for all surveys.

field name	required	default	description
url	yes	-	The endpoint that the webhook will send data to
trigger	yes	-	The event that will trigger the webhook ("responseCreated" or "responseUpdated" or "responseFinished")
surveyIds	no	-	List of survey IDs that will trigger the webhook. If not provided, the webhook will be triggered for all surveys.

Request

POST

/api/v1/webhooks

curl --location --request POST 'https://app.feedbackflowhq.com/api/v1/webhooks' \
--header 'x-api-key: <your-api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "url": "https://mysystem.com/myendpoint",
  "triggers": ["responseFinished"]
}'

Response

{
  "data": {
    "id": "cliu1kdza000219zftad4ip6c",
    "createdAt": "2023-06-13T08:49:04.198Z",
    "updatedAt": "2023-06-13T08:49:04.198Z",
    "url": "https://mysystem.com/myendpoint",
    "environmentId": "clisypjy4000319t4imm289uo",
    "triggers": ["responseFinished"],
    "surveyIds": ["clisypjy4000319t4imm289uo"]
  }
}

DELETE/api/v1/webhooks/<webhook-id>

Delete Webhook by ID

Mandatory Headers

Name
x-Api-Key
Type
string
Description
Your Formbricks API key.

Request

DELETE

/api/v1/webhooks/<webhook-id>

curl --location --request DELETE 'https://app.feedbackflowhq.com/api/v1/webhooks/<webhook-id>' \
--header 'x-api-key: <your-api-key>'

Response

{
  "data": {
    "id": "cliu167rk000019zfhbo68bar",
    "createdAt": "2023-06-13T08:38:02.960Z",
    "updatedAt": "2023-06-13T08:38:02.960Z",
    "url": "https://mysystem.com/myendpoint",
    "environmentId": "clisypjy4000319t4imm289uo",
    "triggers": ["responseFinished"]
  }
}

Webhook Payload

This documentation helps understand the payload structure that will be received when the webhook is triggered in Formbricks.

Variable	Type	Description
webhookId	String	Webhook's Id
event	String	The name of the trigger event [responseCreated, responseUpdated, responseFinished]
data	Object	Contains the details of the newly created response.
data.id	String	Formbricks Response ID.
data.createdAt	String	The timestamp when the response was created.
data.updatedAt	String	The timestamp when the response was last updated.
data.surveyId	String	The identifier of the survey associated with this response.
data.finished	Boolean	A boolean value indicating whether the survey response is marked as finished.
data.data	Object	An object containing the response data, where keys are question identifiers, and values are the corresponding answers given by the respondent.
data.meta	Object	Additional metadata related to the response, such as the user's operating system and browser information.
data.personAttributes	Object	An object with attributes related to the respondent, such as their email and a user ID (if available).
data.person	Object	Information about the respondent, including their unique id, attributes, and creation/update timestamps.
data.notes	Array	An array of notes associated with the response (if any).
data.tags	Array	An array of tags assigned to the response (if any).

An example webhook payload

Payload

{
    "webhookId": "cljwxvjos0003qhnvj2jg4k5i",
    "event": "responseCreated",
    "data": {
        "id": "cljwy2m8r0001qhclco1godnu",
        "createdAt": "2023-07-10T14:14:17.115Z",
        "updatedAt": "2023-07-10T14:14:17.115Z",
        "surveyId": "cljsf3d7a000019cv9apt2t27",
        "finished": false,
        "data": {
            "qumbk3fkr6cky8850bvvq5z1": "Executive"
        },
        "meta": {
            "userAgent": {
                "os": "Mac OS",
                "browser": "Chrome"
            }
        },
        "personAttributes": {
            "email": "test@web.com",
            "userId": "THIS-IS-A-VERY-LONG-USER-ID-FOR-TESTING"
        },
        "person": {
            "id": "cljold01t0000qh8ewzigzmjk",
            "attributes": {
                "email": "test@web.com",
                "userId": "THIS-IS-A-VERY-LONG-USER-ID-FOR-TESTING"
            },
            "createdAt": "2023-07-04T17:56:17.154Z",
            "updatedAt": "2023-07-04T17:56:17.154Z"
        },
        "notes": [],
        "tags": []
    }
}