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.

List Webhooks

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

{
  "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"
      ]
    }
  ]
}

Retrieve Webhook by ID

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

{
  "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"
    ]
  }
}

Create Webhook

Add a webhook to your product.

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"]
}'

{
  "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 Webhook by ID

curl --location --request DELETE 'https://app.formbricks.com/api/v1/webhooks/[webhookId]' \
--header 'x-api-key: <your-api-key>'

{
  "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.

{
    "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": []
    }
}