> ## Documentation Index
> Fetch the complete documentation index at: https://oblodai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/webhooks

Регистрирует (или заменяет) URL проекта для вебхуков и возвращает `secret` для проверки их подписи.
У проекта **один** активный endpoint — повторный вызов заменяет URL и **выдаёт новый секрет**.

**URL:** `https://api.oblodai.com/v1/webhooks` · **Аутентификация:** обязательна.

<Note>
  Примеры используют хелпер `call()` и переменные `$SECRET`/`$PUBLIC_ID` — их определение см. в
  [Как подписать запрос](/guides/signing-requests). Проще не писать подпись руками, а взять
  [SDK](/sdk/overview).
</Note>

<Note>
  **Исключение из формата ответа.** Этот метод возвращает `201 Created` и «голый» объект — **без**
  конверта `state`/`result`. Единственный такой эндпоинт в API.
</Note>

***

## Параметры запроса

<ParamField body="url" type="string" required>
  HTTPS‑URL коллбэка. SSRF‑проверка: приватные и локальные адреса запрещены.
</ParamField>

***

## Пример запроса

<CodeGroup>
  ```bash cURL theme={null}
  BODY='{"url":"https://shop.example/oblodai/callback"}'
  TS=$(date +%s)
  SIG=$(printf '%s\n%s\n%s\n%s' "$TS" 'POST' '/v1/webhooks' "$BODY" \
    | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
  curl -s https://api.oblodai.com/v1/webhooks \
    -X POST -H 'Content-Type: application/json' \
    -H "X-Public-Id: $PUBLIC_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
    -d "$BODY"
  ```

  ```python Python theme={null}
  call("/v1/webhooks", {"url": "https://shop.example/oblodai/callback"})
  ```

  ```js Node.js theme={null}
  await call("/v1/webhooks", { url: "https://shop.example/oblodai/callback" });
  ```
</CodeGroup>

***

## Пример ответа (`201 Created`, без конверта)

```json theme={null}
{
  "endpoint_id": "3f1c…-e2b1",
  "url": "https://shop.example/oblodai/callback",
  "secret": "b7c1e9…"
}
```

<ResponseField name="endpoint_id" type="string">
  Идентификатор endpoint.
</ResponseField>

<ResponseField name="url" type="string">
  Зарегистрированный URL.
</ResponseField>

<ResponseField name="secret" type="string">
  Секрет для проверки подписи вебхуков. **Показывается один раз.**
</ResponseField>

***

## Коды ошибок

| Код                   | Значение                                                      |
| --------------------- | ------------------------------------------------------------- |
| `400 webhook.no_url`  | Не передан `url`.                                             |
| `400 webhook.bad_url` | Некорректный URL или запрещённый (приватный/локальный) адрес. |

***

## Нюансы

* **`secret` показывается один раз** — сохраните его. Он нужен для проверки подписи по
  [алгоритму вебхука](/reference/webhook-object).
* **Один endpoint на проект.** Повторный вызов заменяет URL и выдаёт **новый** секрет (старый
  перестаёт подходить).
* **Per‑объектный `url_callback`** конкретного платежа/выплаты доставляется на свой URL, но
  **подписывается секретом endpoint проекта**. Значит, override работает, только когда endpoint
  зарегистрирован.

***

## Связанные страницы

<CardGroup cols={2}>
  <Card title="Объект вебхука и проверка подписи" href="/reference/webhook-object" icon="arrow-right" horizontal />

  <Card title="POST /v1/webhooks/deliveries" href="/reference/webhooks-deliveries" icon="arrow-right" horizontal />

  <Card title="Настройка вебхуков" href="/guides/webhooks-setup" icon="arrow-right" horizontal />
</CardGroup>