---
title: "Create a webhook"
locale: en
url: https://tlg.builera.app/en/docs/reference/rest/webhooks.create
verified: 2026-10-24
app_version: "2.0"
generated: true
---

# Create a webhook

Create a webhook owned by this connection. Returns the signing secret ONCE (store it now; retry with the same idempotency key returns the same secret) and next_steps: the webhook only counts as set up after webhooks_test returns 2xx. Every type (*) or every account needs the user's confirmation.

Create a webhook owned by this connection. Returns the signing secret ONCE (store it now; retry with the same idempotency key returns the same secret) and next_steps: the webhook only counts as set up after webhooks_test returns 2xx. Every type (*) or every account needs the user's confirmation.

## Overview

| Name | Value |
| --- | --- |
| Code | `webhooks.create` |
| Scope needed | `webhooks.manage` |
| Risk | Write |
| May need confirmation | Yes |
| Runs as | Answers right away |
| Needs `Idempotency-Key` | Yes |
| Member roles allowed | `owner`, `manager`, `agent` |
| In the app | Settings → Webhooks |

## Input fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `text` | Yes |   |
| `description` | `text` | No |   |
| `url` | `text` | Yes |   |
| `eventTypes` | `text[]` | Yes | Concrete types (message.mentioned), group selectors (messages.*) or * for everything. |
| `accountScope` | `object` | No | Default: the caller's accounts (a connection limited to some accounts) or every account. |
| `filters` | `object` | No |   |
| `contentMode` | `"full" \| "thin" \| "none"` | No |   |
| `contentType` | `"application/json" \| "application/cloudevents+json"` | No |   |

## Example request

```bash
curl -X POST https://tlg.builera.app/api/public/v2/ops/webhooks.create \
  -H "Authorization: Bearer $TELEGRAM_AUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique key per operation>" \
  -d '{"name":"…","url":"…","eventTypes":[]}'
```

## Output fields (`data`)

| Field | Type | Required |
| --- | --- | --- |
| `ok` | `true` | Yes |
| `webhook` | `object` | Yes |
| `secret` | `object` | Yes |
| `next_steps` | `object[]` | Yes |

## Example answer

```json
{
  "data": {
    "ok": true,
    "webhook": {
      "url_host": "text",
      "status": "active",
      "status_reason": "text",
      "status_changed_at": "2026-10-22T12:00:00.000Z",
      "owner": {
        "kind": "human",
        "user_id": "00000000-0000-4000-8000-000000000000",
        "connection_id": "00000000-0000-4000-8000-000000000000",
        "connection_name": "text"
      },
      "event_types": [
        "text"
      ],
      "account_scope": {
        "mode": "all"
      },
      "filters": {
        "direction": "in",
        "keywords": {
          "any": [
            "text"
          ],
          "none": [
            "text"
          ]
        },
        "chat_types": [
          "channel"
        ],
        "mention_only": true,
        "exclude_self": true,
        "exclude_sent_by": [
          "campaign"
        ],
        "exclude_connection_ids": [
          "text"
        ],
        "exclude_own_connection": true,
        "include_backfill": true,
        "conversation_ids": [
          "text"
        ],
        "conversation_tags": [
          "text"
        ],
        "has_media": true,
        "person_stage_ids": [
          "text"
        ],
        "campaign_ids": [
          "text"
        ]
      },
      "filters_text": "text",
      "content_mode": "full",
      "content_type": "application/json",
      "revision": 1,
      "verified_at": "2026-10-22T12:00:00.000Z",
      "tested_at": "2026-10-22T12:00:00.000Z",
      "ready": true,
      "consecutive_failures": 1,
      "failing_since": "text",
      "last_success_at": "2026-10-22T12:00:00.000Z",
      "last_failure_at": "2026-10-22T12:00:00.000Z",
      "created_at": "2026-10-22T12:00:00.000Z",
      "updated_at": "2026-10-22T12:00:00.000Z",
      "url": "text",
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "text",
      "description": "text",
      "url_masked": "text"
    },
    "secret": {
      "kid": "text",
      "value": "text",
      "shown_once": true
    },
    "next_steps": [
      {
        "op": "text",
        "mcp_tool": "text",
        "why": "text"
      }
    ]
  }
}
```

## Using it over MCP

Tool `webhooks_create` is listed on the profiles: Full (`full`). On other profiles, find it with `tools_search` and run it with `tools_run`.