Webhook API

Webhook API

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

Before you start managing webhooks, you need to create an API key. This will be used for authorization when making requests to the Webhook API. Please see the API key setup page for more details on how to create and manage your API keys.

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.

Our API has several REST endpoints enabling you to manage these webhooks, providing a great deal of flexibility:

  1. List Webhooks: Retrieve a list of all existing webhooks.
  2. Retrieve Webhook by ID: Retrieve a specific webhook by it's ID.
  3. Create a New Webhook: Add a new webhook to your system.
  4. Get a Specific Webhook: Query the details of a specific webhook using its unique ID.
  5. Delete a Webhook: Remove an existing webhook.

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.


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.formbricks.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/[webhookId]

Retrieve Webhook by ID

Mandatory Headers

  • Name
    x-Api-Key
    Type
    string
    Description

    Your Formbricks API key.

Request

GET
/api/v1/webhooks/[webhookId]
curl --location \
'https://app.formbricks.com/api/v1/webhooks/[webhookId]' \
--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 namerequireddefaultdescription
urlyes-The endpoint that the webhook will send data to
triggeryes-The event that will trigger the webhook ("responseCreated" or "responseUpdated" or "responseFinished")
surveyIdsno-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.formbricks.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/[webhookId]

Delete Webhook by ID

Mandatory Headers

  • Name
    x-Api-Key
    Type
    string
    Description

    Your Formbricks API key.

Request

DELETE
/api/v1/webhooks/[webhookId]
curl --location --request DELETE 'https://app.formbricks.com/api/v1/webhooks/[webhookId]' \
--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.

VariableTypeDescription
webhookIdStringWebhook's Id
eventStringThe name of the trigger event [responseCreated, responseUpdated, responseFinished]
dataObjectContains the details of the newly created response.
data.idStringFormbricks Response ID.
data.createdAtStringThe timestamp when the response was created.
data.updatedAtStringThe timestamp when the response was last updated.
data.surveyIdStringThe identifier of the survey associated with this response.
data.finishedBooleanA boolean value indicating whether the survey response is marked as finished.
data.dataObjectAn object containing the response data, where keys are question identifiers, and values are the corresponding answers given by the respondent.
data.metaObjectAdditional metadata related to the response, such as the user's operating system and browser information.
data.personAttributesObjectAn object with attributes related to the respondent, such as their email and a user ID (if available).
data.personObjectInformation about the respondent, including their unique id, attributes, and creation/update timestamps.
data.notesArrayAn array of notes associated with the response (if any).
data.tagsArrayAn 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": []
    }
}

Was this page helpful?