> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/codev/integrations/notifications/webhooks.md). # Webhooks Webhooks deliver build and release events from codev to any HTTP endpoint. When a build completes, a build fails, or a release is deployed or finalized, codev sends an HTTP request to the URL you configure — carrying a stable event payload you can reshape into whatever body your destination expects. Unlike the [Slack](/flxbl/codev/integrations/notifications/slack.md) and [Microsoft Teams](/flxbl/codev/integrations/notifications/teams.md) integrations, which post preformatted messages to a chat channel, a webhook is a raw delivery to an endpoint you control: an automation server, an internal service, a serverless function, or a chat provider's own incoming webhook. You manage webhooks under **Settings > Webhooks**. Each webhook has its own delivery log, retry policy, and error count.
The webhooks list under Settings

Each webhook shows its event, provider, status, error count, and last delivery, with actions to view its delivery history, edit it, or delete it.

## What gets delivered A webhook fires on one event. codev emits four events to webhooks: | Event | When it fires | Key `data` fields | | ------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------- | | **Release Deployed** (`release.deployed`) | A release finishes deploying to an environment | `releaseName`, `domain`, `environmentName`, `environmentCategory`, `deploymentStatus` | | **Release Finalized** (`release.finalized`) | A release is finalized | `releaseName`, `domain`, `intermediateCandidatesFinalized` | | **Build Completed** (`build.completed`) | A build completes after a merge | `commitId`, `buildStatus`, `buildResults`, `workItems` | | **Build Failed** (`build.failed`) | A build fails | `commitId`, `buildStatus`, `buildResults` | ## The event payload Every event is delivered with the same envelope. Event-specific fields live under `data`; the envelope fields are hoisted to the top level so a body template can reference them the same way for any event. ```json { "event": "release.deployed", "repository": "acme/core", "timestamp": "2026-08-04T13:03:00.000Z", "actor": "developer@acme.com", "data": { "releaseName": "1.4.0", "domain": "core", "environmentName": "production", "environmentCategory": "release", "deploymentStatus": "Success" } } ``` With no body template, codev sends this payload as-is. A body template lets you send a different shape (see [Shape the request body](#shape-the-request-body)). ## Create a webhook 1. Go to **Settings > Webhooks** and click **Add Webhook**. 2. Give it a **Name** and pick the **Event** it fires on. 3. Enter the **Webhook URL** and the HTTP **Method** (`POST`, `PUT`, or `PATCH`). 4. Add any **Headers** the destination needs — an authorization token, a content type, a signing header. 5. Set the **Timeout**, **Retry Count**, and **Retry Delay** (see [Timeouts and retries](#timeouts-and-retries)). 6. Optionally add a **Body Template** to reshape the payload. 7. Click **Add Webhook**. The **Provider** field tags the destination type. Leave it on **Custom** to deliver to any HTTP endpoint.
The Add Webhook dialog with the event, URL, method, retry settings, and body-template editor

A webhook's configuration — event, destination URL and method, headers, timeout and retry policy, and the body-template editor with the merge-field reference alongside it.

## Shape the request body By default codev delivers the [event payload](#the-event-payload) verbatim. A **Body Template** rewrites it into the shape your destination expects. The template is JSON; to pull a value from the event, use a `$path` reference: ```json { "$path": "data.releaseName" } ``` codev replaces each `{ "$path": "…" }` with the value at that path in the event payload, and sends the resulting JSON as the request body. Everything else in the template is sent literally, so you can mix static fields with pulled values. Leaving the template empty sends the raw event payload. The editor validates the JSON as you type and lists the merge fields available for the selected event beside it, in two groups: the **envelope** fields present on every event, and the event-specific **`data`** fields. Click a field to insert its `$path` reference, or type inside a `$path` string for autocomplete.
The body-template editor with the envelope and event-specific merge-field groups

The body-template editor reshapes the event into the body your destination expects. The reference panel lists the envelope fields and the selected event's data fields; each inserts a $path reference.

For example, to post a message to an endpoint that expects `text`, `release`, `environment`, and `status`: ```json { "text": { "$path": "event" }, "release": { "$path": "data.releaseName" }, "environment": { "$path": "data.environmentName" }, "status": { "$path": "data.deploymentStatus" } } ``` A `release.deployed` event then delivers: ```json { "text": "release.deployed", "release": "1.4.0", "environment": "production", "status": "Success" } ``` ## Timeouts and retries Each delivery has a per-attempt **Timeout** (default 30000 ms). If the endpoint returns a non-2xx status or does not respond within the timeout, codev retries up to **Retry Count** times (default 3), waiting **Retry Delay** (default 1000 ms) between attempts. A delivery is a success once any attempt returns a 2xx; it is a failure once the retries are exhausted, and the webhook's error count increases. ## Monitor deliveries Open a webhook's **Delivery history** from the list to see every delivery, with totals and a success rate. Filter by status — all, success, failed, or retrying — and select a delivery to inspect its **Overview**, **Request**, **Response**, and per-**Attempts** timeline, including the response code and duration. **Retry** re-sends a delivery on demand.
A webhook's delivery history with per-delivery request, response, and attempts

The delivery history — totals and success rate, a filterable list of deliveries, and the selected delivery's overview, request, response, and attempt timeline, with a manual retry.

## Troubleshooting * **No deliveries arrive** — confirm the webhook's status is **Active** and its **Event** matches what you expect to fire. Only the four events above are delivered. * **Deliveries fail** — open the delivery's **Response** and **Attempts** to see the status code and error. A 4xx usually means the body or headers are wrong for the destination; a timeout means the endpoint was slow — raise the **Timeout** or check the endpoint. * **The endpoint expects a specific shape** — add a [body template](#shape-the-request-body) so codev sends exactly the fields it needs. {% content-ref url="/pages/4uZHFEGGOGb26NhSg55F" %} [Slack](/flxbl/codev/integrations/notifications/slack.md) {% endcontent-ref %} {% content-ref url="/pages/4VSBqVSVLTcDV9wYI8lQ" %} [Microsoft Teams](/flxbl/codev/integrations/notifications/teams.md) {% endcontent-ref %} {% content-ref url="/pages/GQ9RQsUxYj0j0ZcBrGUq" %} [Integrations](/flxbl/codev/integrations/overview.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.flxbl.io/flxbl/codev/integrations/notifications/webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.