---
title: Web Callouts
description: Trigger an HTTP callout from a trace, observation, or session in Langfuse.
sidebarTitle: Web Callouts
---

# Web Callouts

Web Callouts let project members trigger a configured backend HTTP request from a trace, observation, or session in the Langfuse UI. Use them to connect debugging workflows to internal tools, support systems, incident workflows, or custom investigation services.

Unlike [prompt webhooks](/docs/prompt-management/features/webhooks-slack-integrations), Web Callouts are manually triggered from the UI. Langfuse sends the request synchronously from the backend when the user clicks the action.

  Web Callouts send identifiers only: trace/observation/session ID and the project id.
  Fetch additional data from the Langfuse API in your own backend if your workflow needs it.

## Configure a Web Callout

Open **Project Settings** > **Integrations** > **Web Callouts** and create a callout endpoint. You need Admin/Owner (`integrations:CRUD`) permissions to configure new callouts.
Callouts are configured per project and can be invoked by **all** users in a project.

Configure:

- **Name:** shown in the action menu, for example `Add to Support Tool`.
- **URL:** HTTP or HTTPS endpoint that accepts `POST` requests. Custom ports are supported.
- **Success toast message:** shown after your endpoint returns a successful response.
- **Enabled:** disabled callouts are hidden from the action menu.
- **Request headers:** optional static headers, for example `Authorization: Bearer <token>`.

## Trigger a Web Callout

After setup, users with project read access can trigger the callout from:

- The action menu on trace details.
- The action menu on observation details.
- The session details header.

Langfuse sends the request immediately when the user clicks the action. The UI shows a success toast only after your endpoint returns a 2xx response.
The request times out after 5 seconds. Calls will not be retried and are rate limited.

## Request Payload

Langfuse sends a JSON `POST` request with this structure:

```json filename="web-callout-payload.json"
{
  "version": 1,
  "items": [
    {
      "projectId": "project-id",
      "traceId": "trace-id",
      "observationId": null,
      "sessionId": "session-id"
    }
  ]
}
```

Note: all ID fields except for the `projectId` are nullable.
Langfuse validates that the trace, observation, and session belong to the project before sending the request.

## Endpoint Requirements

Your endpoint must:

- Accept `POST` requests with `Content-Type: application/json`.
- Return any HTTP 2xx status within 5 seconds.

Langfuse treats non-2xx responses, network errors, invalid URLs, and timeouts as failed callouts and shows an error toast.

Web Callouts are not retried and Langfuse does not keep a delivery log.

## Authentication and Headers

You can configure static request headers for authentication, for example `Authorization` or `X-API-Key`.
Header values are encrypted at rest and are sent from the Langfuse backend. When editing an existing header without changing its name, leaving the value empty keeps the stored encrypted value.

Langfuse sets `Content-Type: application/json` and `User-Agent: Langfuse/1.0` automatically.
The following header names cannot be configured: `content-length`, `content-type`, `cookie`, and `host`.

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/docs/observability/features/web-callouts.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.