Webhooks

Configure webhooks to receive real-time notifications

Webhooks allow you to receive real-time HTTP notifications when events occur in Formbricks, such as new survey responses.

The Webhook Object

Attributes

id · string

Unique identifier for the webhook

createdAt · string

ISO 8601 timestamp of when the webhook was created

updatedAt · string

ISO 8601 timestamp of when the webhook was last updated

environmentId · string

The environment this webhook belongs to

url · string

The URL where webhook events will be sent

triggers · array

Array of event types that trigger this webhook

surveyIds · array

Optional array of survey IDs to filter events (empty = all surveys)

name · string

Optional friendly name for the webhook

source · string

Source of the webhook (e.g., “user”, “zapier”)

List Webhooks

Retrieve all webhooks for your environments.

cURL

curl https://app.formbricks.com/api/v1/webhooks \
  -H "x-api-key: YOUR_API_KEY"

Response

[
  {
    "id": "wbh_...",
    "createdAt": "2021-01-01T00:00:00.000Z",
    "updatedAt": "2021-01-01T00:00:00.000Z",
    "environmentId": "env_...",
    "url": "https://your-app.com/webhooks/formbricks",
    "triggers": ["responseCreated", "responseFinished"],
    "surveyIds": [],
    "name": "Production Webhook",
    "source": "user"
  }
]

Retrieve a Webhook

Get a specific webhook by ID.

cURL

curl https://app.formbricks.com/api/v1/webhooks/{webhookId} \
  -H "x-api-key: YOUR_API_KEY"

Path Parameters

webhookId · string · required

The ID of the webhook to retrieve

Create a Webhook

Create a new webhook to receive event notifications.

cURL

curl -X POST https://app.formbricks.com/api/v1/webhooks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environmentId": "env_...",
    "url": "https://your-app.com/webhooks/formbricks",
    "triggers": ["responseCreated", "responseFinished"],
    "name": "Production Webhook"
  }'

Body Parameters

environmentId · string · required

The environment ID for this webhook

url · string · required

The URL where webhook events will be sent (must be HTTPS)

triggers · array · required

Array of event types: responseCreated, responseUpdated, responseFinished

name · string

Friendly name for the webhook

surveyIds · array

Optional array of survey IDs to filter events. Empty array means all surveys.

source · string

Source identifier (e.g., “user”, “zapier”, “make”)

Response

Returns the created webhook object.

Delete a Webhook

Delete a webhook to stop receiving notifications.

cURL

curl -X DELETE https://app.formbricks.com/api/v1/webhooks/{webhookId} \
  -H "x-api-key: YOUR_API_KEY"

Path Parameters

webhookId · string · required

The ID of the webhook to delete

Webhook Events

Available Triggers

Event Payload

When an event occurs, Formbricks sends a POST request to your webhook URL:

{
  "event": "responseFinished",
  "environmentId": "env_...",
  "surveyId": "srv_...",
  "response": {
    "id": "res_...",
    "createdAt": "2021-01-01T00:00:00.000Z",
    "updatedAt": "2021-01-01T00:00:00.000Z",
    "surveyId": "srv_...",
    "contactId": "con_...",
    "finished": true,
    "data": {
      "qst_1": "Great product!",
      "qst_2": 5
    },
    "variables": {},
    "ttc": {
      "qst_1": 12,
      "qst_2": 3
    },
    "meta": {
      "source": "app",
      "url": "https://example.com/dashboard",
      "userAgent": {
        "browser": "Chrome",
        "os": "Windows",
        "device": "desktop"
      },
      "country": "US"
    },
    "contactAttributes": {
      "email": "[e-mail]"
    },
    "language": "en"
  }
}

Webhook Endpoint Requirements

HTTPS Only

Webhook URLs must use HTTPS (except for localhost during development).

Response Time

Your endpoint should respond within 5 seconds. Long-running operations should be queued.

Status Codes

Return a 2xx status code to acknowledge receipt. Any other status code will be treated as a failure.

Example Endpoint

Node.js (Express)

app.post('/webhooks/formbricks', express.json(), (req, res) => {
  const { event, response } = req.body;
  
  // Process the webhook asynchronously
  processWebhook(event, response).catch(err => {
    console.error('Webhook processing error:', err);
  });
  
  // Respond immediately
  res.status(200).json({ received: true });
});

async function processWebhook(event, response) {
  if (event === 'responseFinished') {
    // Handle finished response
    await saveToDatabase(response);
    await sendNotification(response);
  }
}

Retry Logic

Formbricks implements automatic retries for failed webhook deliveries:

• Retries with exponential backoff
• Up to 3 retry attempts
• Webhooks are marked as failed after all retries are exhausted

Security

Verify Webhook Source

To verify webhooks are from Formbricks:

1. IP Allowlist: Restrict webhook endpoint to Formbricks IP addresses
2. Shared Secret: Include a secret token in the webhook URL query string
3. Validate Payload: Verify the payload structure matches expected format

Example with Secret Token

// Create webhook with secret in URL
const webhookUrl = 'https://your-app.com/webhooks/formbricks?token=your_secret_token';

// In your endpoint
app.post('/webhooks/formbricks', (req, res) => {
  const token = req.query.token;
  
  if (token !== process.env.WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  // Process webhook...
});

Testing Webhooks

Use tools like ngrok or webhook.site to test webhooks during development:

# Start ngrok tunnel
ngrok http 3000

# Use the HTTPS URL as your webhook URL
https://abc123.ngrok.io/webhooks/formbricks

Filtering by Survey

To receive events only for specific surveys, set the surveyIds array:

{
  "environmentId": "env_...",
  "url": "https://your-app.com/webhooks/survey-specific",
  "triggers": ["responseFinished"],
  "surveyIds": ["srv_123", "srv_456"]
}

Leave surveyIds empty or omit it to receive events for all surveys.