---
canonical_url: "https://docs.composio.dev/reference/api-reference/session-webhooks/composio_session_hook_before_execute"
markdown_url: "https://docs.composio.dev/reference/api-reference/session-webhooks/composio_session_hook_before_execute.md"
product: "platform"
version: "3.1"
last_updated: null
---

# Session hook: before execute

**Documentation:** /reference/api-reference/session-webhooks/composio_session_hook_before_execute

> **API version:** This page documents Composio REST API v3.1, the current version, at `https://backend.composio.dev/api/v3.1`. `https://backend.composio.dev/api/v3` is the previous version and remains supported.

Sent before a tool or proxy call runs, when the session has a `before_execute` hook with a `webhook` handler. Composio waits for your answer, then runs the call, blocks it, or runs it with your changes.

---

## POST `composio.session_hook.before_execute`

**Event type:** `composio.session_hook.before_execute`

**Summary:** Session hook: before execute

Sent before a tool or proxy call runs, when the session has a `before_execute` hook with a `webhook` handler. Composio waits for your answer, then runs the call, blocks it, or runs it with your changes.

### Delivery Headers

- `webhook-id` (string) *(required)*: Unique request id. Equals the payload `id`.
- `webhook-timestamp` (string) *(required)*: Unix timestamp (seconds) of when the request was sent.
- `webhook-signature` (string) *(required)*: Base64 HMAC-SHA256 signature made with your session webhook secret, formatted `v1,<signature>`, over `${webhook-id}.${webhook-timestamp}.${raw_body}`.

### Request Body

**Schema:**

- `id` (string) *(required)*: Unique request id (msg_<uuid>). Also sent as the `webhook-id` header.
- `timestamp` (string (date-time)) *(required)*: ISO 8601 timestamp of when the request was created.
- `type` (enum: "composio.session_hook.before_execute") *(required)*
- `metadata` (object) *(required)*
  - `project_id` (string) *(required)*: ID of the project.
  - `session_id` (string) *(required)*: ID of the session the call was made in.
  - `user_id` (string) *(required)*: ID of the user the session belongs to.
  - `hook_id` (string) *(required)*: ID of the hook that sent this request, as set on the session.
- `data` (any) *(required)*: The call about to run. `type` says whether it is a tool call or a proxy call.

**Example:**

```json
{
  "id": "msg_6f1d2c3b-8a4e-4f6a-9b1c-2d3e4f5a6b7c",
  "type": "composio.session_hook.before_execute",
  "timestamp": "2026-11-11T10:30:00Z",
  "metadata": {
    "project_id": "proj_abc123",
    "session_id": "trs_abc123",
    "user_id": "user_123",
    "hook_id": "email_policy"
  },
  "data": {
    "type": "tool_execute",
    "tool_call": {
      "toolkit_slug": "gmail",
      "tool_slug": "GMAIL_SEND_EMAIL",
      "toolkit_version": "20261101_00",
      "connected_account_id": "ca_def456",
      "arguments": {
        "recipient_email": "jane@customer.com",
        "subject": "Pricing",
        "body": "Our floor price is $40 per seat."
      }
    }
  }
}
```

### Responses

#### 200 - Answer with HTTP 200 and a JSON body that says what to do with the call. Any other status, a body that doesn't match (a misspelled field included), or no answer within the hook's `timeout_ms` counts as a failure: Composio doesn't retry, and the hook's `fallback_action` applies. Fields you don't use can be left out or sent as null.

**Response Schema:**

*One of:*
  - `action` (enum: "continue") *(required)*: Let the call run.
  - `message` (string,null): Not used when the call goes ahead.
  - `override` (any): Run the call with these changes. Use `tool_call` for a tool call and `http_request` for a proxy call; the other one counts as an answer that does not match.
  - `action` (enum: "block") *(required)*: Stop the call.
  - `message` (string) *(required)*: Why the call was stopped. Shown to the agent.

**Example Response:**

```json
{
  "action": "block",
  "message": "jane@customer.com is outside acme.com"
}
```

---

## REST API version

The current REST API version is **v3.1**, served at `https://backend.composio.dev/api/v3.1`. Prefer it for new code and new examples.

`https://backend.composio.dev/api/v3` is the previous version. It is frozen with pinned tool-version defaults and remains supported — existing v3 integrations keep working and do not need to migrate.