# Webhook configuration

> For the complete documentation index, see [llms.txt](/llms.txt)

> PushFeedback sends feedback as a POST request to an HTTPS endpoint you control. Use webhooks to connect PushFeedback with an internal service or a tool without a dedicated integration.

PushFeedback sends feedback as a POST request to an HTTPS endpoint you control. Use webhooks to connect PushFeedback with an internal service or a tool without a dedicated integration.

:::info
Integrations are only available on the [Professional](https://pushfeedback.com#pricing) and [Unlimited](https://pushfeedback.com#pricing) plans. On the free plan, use [email notifications](./email.md) instead.
:::

![Webhook configuration editor](./images/webhook-configuration.jpg)

## Prerequisites

- A PushFeedback account. If you don't have one, [sign up for free](https://app.pushfeedback.com/accounts/signup/).
- A project created in your PushFeedback dashboard. If you haven't created one yet, follow the steps in the [Quickstart](../quickstart.md#2-create-a-project) guide.

## Configure a webhook

1. Open [app.pushfeedback.com](https://app.pushfeedback.com) and log in.

2. Go to **Projects** and select your project.

3. Click **Settings**, then under **Integrations**, select **Webhook**.

4. Enter a public HTTPS endpoint on port 443. Redirects are rejected.

5. Set the event title and message template. You can insert supported variables directly:

    ```text
    {{ feedback.message }}
    {{ feedback.rating_label }}
    {{ feedback.sentiment }}
    {{ feedback.email }}
    {{ feedback.url }}
    {{ feedback.detail_url }}
    {{ project.name }}
    ```

    Static text stays yours. Feedback values are formatted safely for the destination.

6. Optionally pause delivery, require a message, set **Delivery rules (JSON)**, or add **Custom fields (JSON)**. The editor validates rules and mappings before saving.

7. On wider screens, inspect the **Event preview** while you edit. It uses the project's latest feedback, or sample data when the project is empty, and does not contact your endpoint.

8. Select **Test connection** to POST a small `pushfeedback.webhook_connection_test` event to the entered endpoint. It is a real request, so point it at a test-safe handler. The request uses HTTPS, rejects redirects, and reports only a connection result.

9. Save the integration.

## Delivery behavior

When the integration is enabled, feedback matching your delivery controls and rules is sent to the configured webhook endpoint.

## Webhook specification

The exact event payload depends on your templates and custom fields. Use the editor preview for the payload that your configuration will send. A feedback delivery contains an event envelope and rendered feedback data, similar to this example:

```json
{ "id": "EVNT-feedback123",
  "object": "event",
  "creation_time": "2026-08-04T08:00:00Z",
  "type": "feedback.created",
  "api_version": "v1",
  "data": { "object": "feedback",
    "id": "feedback123",
    "project_id": "https://docs.example.com",
    "session": "visitor-session",
    "message": "This is a sample feedback message.",
    "metadata": "{\"browser\":\"Firefox\"}",
    "url": "https://example.com/page",
    "rating": 4,
    "rating_mode": "stars",
    "has_screenshot": true,
    "screenshot_url": "https://app.pushfeedback.com/api/feedback/feedback123/screenshot/",
    "pushfeedback_url": "https://app.pushfeedback.com/team1/projects/project1/",
    "text": "New feedback on PushFeedback: https://app.pushfeedback.com/team1/projects/project1/",
    "title": "New feedback on Developer docs",
    "body": "This is a sample feedback message.\n\nRating: 4 stars",
    "fields": { "priority": "positive"}},
  "delivery_id": 42}
```

Feedback deliveries include these request headers:

```text
Content-Type: application/json
Idempotency-Key: pushfeedback-delivery-42
User-Agent: PushFeedback webhook delivery
X-PushFeedback-Event: feedback.created
```

Treat `Idempotency-Key` as the stable identifier for a delivery if your endpoint performs its own deduplication.

## Remove the integration

To disconnect the webhook, go to the integration's settings page in your PushFeedback dashboard and click **Remove integration**. Confirming stops the integration from firing on new feedback immediately.