> For the complete documentation index, see [llms.txt](https://docs.betterbugs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.betterbugs.io/product-features/integrations/webhook.md).
# Webhook
### What is a Webhook?
A webhook enables an application to send real-time data or notifications to other systems. It’s an event-driven mechanism to integrate systems that works like a reverse user-defined API callback over HTTP using the POST method.
Simply put, it's a lightweight way for one system to communicate with and notify another system over HTTP about an event or a change.
> **For instance**, if you want to retrieve data about a bug captured via BetterBugs.io in your application, your application’s webhook URL added to BetterBugs.io can immensly simplify this process.
>
> Here's how it works.
>
> Rather than having your application initiate an API call to fetch data from BetterBugs.io, the webhook URL (serving as your application's endpoint) enables BetterBugs.io to perform a POST request automatically.
>
> This request delivers the complete data (as a **JSON payload** OR **Form Data**) directly to your application. Your app can then process the payload and utilize the retrieved information as required.
### How does the Webhook Integration Work?
Here’s how it works:
1. **Setup** — Your application provides a webhook URL to BetterBugs.io. This Webhook URL acts as the endpoint where data will be delivered.
2. **Event Trigger** — When you create a report with BetterBugs.io and share it with your application, BetterBugs.io dispatches an **HTTP POST** request to the set webhook URL.
3. **Payload Delivery** — The HTTP request contains the event data (payload) in a **JSON format** or **Form Data format**, which gets delivered to your application and can then be processed as required.
### Example Use Case for BetterBugs.io Webhook Integration
If you have a project management app, you can integrate a webhook to retrieve all the information for the software issue or bug captured using BetterBugs.io to send it to your application backend servers.
Your application can then process the sent data (such as bugId, workspaceId, projectId, description, status, priority, type, sessionUrl, and others), visualize, display, or use it as required on the frontend.
### What are the Key Benefits of Using BetterBugs.io Webhook Integration?
Benefits of using BetterBugs.io webhook:
* Send technical data and developer-friendly details of the bugs to your project tools and issue trackers.
* Save massive time, resources, and manual effort for bug reporting and debugging workflows.
* Cut back on to-and-fro communication for reporting and fixing bugs, and manual copy-pasting of information.
### How to Add Your App Webhook URL to BetterBugs.io: Step-by-Step
Adding your webhook is super simple. Here are the steps for it:
{% stepper %}
{% step %}
#### Open Workspace Settings > Integrations
Click on BetterBugs Workspace name at the top left side of app screen. Now, click the **gear icon** to open **Workspace Settings** > **Integrations**.
{% endstep %}
{% step %}
#### Search Webhook
In the **Integrations** tab, search for **Webhook** and click to open the **Webhook** card.
{% endstep %}
{% step %}
#### Turn off workspace-wide integration
Toggle off the "**All Projects**" option and hit "**Continue**". You should see the "**Manage per project**" option now.
{% hint style="info" %}
By default, its turned on for workspace level integration. For project-wise integration, you need to disable "**All Projects**".
{% endhint %}
{% endstep %}
{% step %}
#### Select a BetterBugs project to integrate and hit "Connect"
Select a project from the projects name list (that's within your Workspace). From the "**Actions**" column, hit "**Connect**" for that project.
{% endstep %}
{% step %}
#### Enter Webhook URL\*
In the "**Configure webhook integration**" modal, enter your **Webhook URL\*** and click "**Verify**".
{% hint style="info" %}
Note that the URL endpoint should respond with a **2XX series response code** (such as 200, 201, or 204) when the verify request is dispatched.
{% endhint %}
{% endstep %}
{% step %}
#### Enter Other Details: Payload Format\*, Custom Headers, Custom Fields
Once your Webhook URL is validated and verified, add the:
* **Payload Format\***: JSON or Form Data
* **Custom Headers** (Optional)
* **Custom Fields** (Optional)
{% endstep %}
{% step %}
#### Confirm
Click "**Add Webhook**" to confirm action.
{% endstep %}
{% endstepper %}
Okay! You're all set with the Webhook integration.
### Sample JSON Payload sent by BetterBugs.io using a Webhook URL
Here’s what the payload looks like being sent via webhook:
```json
{
"customFields": {
"field1": "data1",
"field2": "data2"
},
"bugId": "682c1dbb3b574d66f3863324",
"projectId": "68088dd3077eafee5d46cf86",
"workspaceId": "68088dd2077eafee5d46cf83",
"userId": "66dea4b99fee48c5dcdc1d2c",
"title": "Sample Bug title",
"description": "Sample Bug Description:
Summary:
Multiple attempts to configure webhook integration failed due to an active API key not being found for the project, preventing successful connection setup.
Steps to reproduce bug:
- First step
",
"status": "OPEN",
"priority": "HIGH",
"type": "screenshot",
"createdAt": "2025-05-20T06:14:18.814Z",
"updatedAt": "2025-05-20T06:14:27.491Z",
"metadata": [],
"assignees": [{
"email": "quinn@example.com",
"id": "66dea4b99fee48c5dcdc1d2c",
"name": "quinn"
}],
"sessionUrl": "https://app.betterbugs.io/session/682c1dbb3b574d66f3863324",
"screenshotUrl": "https://cdn.betterbugs.io/workspace/69a039e216ab18c8c2a1d0c8/69a039e216ab18c8c2a1d0cc/69bd2da39b22f777f76cdd14/s-1774005668325-WQGA.png"
}
```