---
metadata:
  - name: generator
    content: Diplodoc Platform v5.55.3
alternate:
  - https://pay.yandex.ru/docs/en/custom/backend/merchant-api/webhook.md
  - https://pay.yandex.ru/docs/ru/custom/backend/merchant-api/webhook.md
  - href: en/custom/backend/merchant-api/webhook.md
    type: text/markdown
    title: Markdown version
  - href: ../../../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://pay.yandex.ru/docs/en/llms.txt

<!-- source: en/custom/backend/merchant-api-hidden/webhook.md -->
<div class="openapi">

# /v1/webhook

<!-- markdownlint-disable-file -->

Notifications of status change.

The request is sent when changing the order status.

Supported events:
- `ORDER_STATUS_UPDATED` - a change in the payment status or delivery status
- `OPERATION_STATUS_UPDATED` - a change in the status of the operation to confirm, cancel, or refund a payment

## Request

<div class="openapi__requests">

<div class="openapi__request__wrapper" style="--method: var(--dc-openapi-methods-post);margin-bottom: 12px">

<div class="openapi__request">

POST {.openapi__method}
```text translate=no
https://example.merchant.ru/v1/webhook
```

</div>

Production

</div>

<div class="openapi__request__wrapper" style="--method: var(--dc-openapi-methods-post);margin-bottom: 12px">

<div class="openapi__request">

POST {.openapi__method}
```text translate=no
https://sandbox.example.merchant.ru/v1/webhook
```

</div>

Sandbox

</div>

</div>

<div class="openapi-entity">

### Body

{% cut "application/json" %}

```json translate=no
{
  "event": "TRANSACTION_STATUS_UPDATE",
  "eventTime": "2025-01-01T00:00:00Z",
  "merchantId": "123e4567-e89b-12d3-a456-426614174000",
  "operation": {
    "externalOperationId": "example",
    "operationId": "123e4567-e89b-12d3-a456-426614174000",
    "operationType": "AUTHORIZE",
    "orderId": "example",
    "pointsUpdated": true,
    "status": "PENDING"
  },
  "order": {
    "deliveryStatus": "NEW",
    "orderId": "example",
    "paymentStatus": "PENDING"
  },
  "subscription": {
    "customerSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
    "nextWriteOff": "2025-01-01T00:00:00Z",
    "status": "NEW",
    "subscriptionPlanId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

{% endcut %}

#|
|| **Name** | **Description** ||
||

_event_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

_Enum:_{.json-schema-reset .json-schema-value} `TRANSACTION_STATUS_UPDATE`, `ORDER_STATUS_UPDATED`, `OPERATION_STATUS_UPDATED`, `SUBSCRIPTION_STATUS_UPDATED`
{.table-cell}
||
||

_eventTime_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string&lt;date-time&gt;

Event time in the format `RFC 3339`; `YYYY-MM-DDThh:mm:ssTZD`

_Example:_{.json-schema-reset .json-schema-example} `2025-01-01T00:00:00Z`
{.table-cell}
||
||

_merchantId_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string&lt;uuid&gt;

_Example:_{.json-schema-reset .json-schema-example} `123e4567-e89b-12d3-a456-426614174000`
{.table-cell}
||
||

_operation_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: [OperationWebhookData](#entity-OperationWebhookData)

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "externalOperationId": "example",
  "operationId": "123e4567-e89b-12d3-a456-426614174000",
  "operationType": "AUTHORIZE",
  "orderId": "example",
  "pointsUpdated": true,
  "status": "PENDING"
}
```

{% endcut %}
{.table-cell}
||
||

_order_{.json-schema-reset .json-schema-property}
{.table-cell}|
{% cut "**All of 1 type**" %}{.json-schema-combinators data-marker=and}

- **Type**: [OrderWebhookData](#entity-OrderWebhookData)

  {% cut "**Example**" %}{.json-schema-example}

  ```json translate=no
  {
    "deliveryStatus": "NEW",
    "orderId": "example",
    "paymentStatus": "PENDING"
  }
  ```

  {% endcut %}

{% endcut %}

if event == ORDER_STATUS_UPDATED

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "deliveryStatus": "NEW",
  "orderId": "example",
  "paymentStatus": "PENDING"
}
```

{% endcut %}
{.table-cell}
||
||

_subscription_{.json-schema-reset .json-schema-property}
{.table-cell}|
{% cut "**All of 1 type**" %}{.json-schema-combinators data-marker=and}

- **Type**: [SubscriptionWebhookData](#entity-SubscriptionWebhookData)

  {% cut "**Example**" %}{.json-schema-example}

  ```json translate=no
  {
    "customerSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
    "nextWriteOff": "2025-01-01T00:00:00Z",
    "status": "NEW",
    "subscriptionPlanId": "123e4567-e89b-12d3-a456-426614174000"
  }
  ```

  {% endcut %}

{% endcut %}

Subscription status. Transmitted if event == SUBSCRIPTION_STATUS_UPDATED.

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "customerSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
  "nextWriteOff": "2025-01-01T00:00:00Z",
  "status": "NEW",
  "subscriptionPlanId": "123e4567-e89b-12d3-a456-426614174000"
}
```

{% endcut %}
{.table-cell}
||
|#{.json-schema-properties}

</div>

<div class="openapi-entity">

### OperationWebhookData {#entity-OperationWebhookData}

#|
|| **Name** | **Description** ||
||

_operationId_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string&lt;uuid&gt;

_Example:_{.json-schema-reset .json-schema-example} `123e4567-e89b-12d3-a456-426614174000`
{.table-cell}
||
||

_operationType_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

_Enum:_{.json-schema-reset .json-schema-value} `AUTHORIZE`, `BIND_CARD`, `REFUND`, `CAPTURE`, `VOID`, `RECURRING`, `PREPAYMENT`, `SUBMIT`
{.table-cell}
||
||

_orderId_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_status_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

_Enum:_{.json-schema-reset .json-schema-value} `PENDING`, `SUCCESS`, `FAIL`
{.table-cell}
||
||

_externalOperationId_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_pointsUpdated_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: boolean

Shows whether Plus points have been updated. If yes, sync the cart.
{.table-cell}
||
|#{.json-schema-properties}

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "externalOperationId": "example",
  "operationId": "123e4567-e89b-12d3-a456-426614174000",
  "operationType": "AUTHORIZE",
  "orderId": "example",
  "pointsUpdated": true,
  "status": "PENDING"
}
```

{% endcut %}

</div>

<div class="openapi-entity">

### OrderWebhookData {#entity-OrderWebhookData}

#|
|| **Name** | **Description** ||
||

_orderId_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

Order ID received in the /order/create response

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_deliveryStatus_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Delivery statuses

_Enum:_{.json-schema-reset .json-schema-value} `NEW`, `ESTIMATING`, `EXPIRED`, `READY_FOR_APPROVAL`, `COLLECTING`, `PREPARING`, `DELIVERING`, `DELIVERED`, `RETURNING`, `RETURNED`, `FAILED`, `CANCELLED`, `null`

_Example:_{.json-schema-reset .json-schema-example} `NEW`
{.table-cell}
||
||

_paymentStatus_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Order status

_Enum:_{.json-schema-reset .json-schema-value} `PENDING`, `AUTHORIZED`, `CAPTURED`, `VOIDED`, `REFUNDED`, `CONFIRMED`, `PARTIALLY_REFUNDED`, `FAILED`, `null`

_Example:_{.json-schema-reset .json-schema-example} `PENDING`
{.table-cell}
||
|#{.json-schema-properties}

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "deliveryStatus": "NEW",
  "orderId": "example",
  "paymentStatus": "PENDING"
}
```

{% endcut %}

</div>

<div class="openapi-entity">

### SubscriptionWebhookData {#entity-SubscriptionWebhookData}

#|
|| **Name** | **Description** ||
||

_customerSubscriptionId_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string&lt;uuid&gt;

Subscription ID. The SDK returns it when the subscription is created successfully. You can also save a subscription when you get the first notification on it. The same value will arrive in this field every time the subscription is updated.

_Example:_{.json-schema-reset .json-schema-example} `123e4567-e89b-12d3-a456-426614174000`
{.table-cell}
||
||

_status_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

Subscription type

_Enum:_{.json-schema-reset .json-schema-value} `NEW`, `ACTIVE`, `CANCELLED`, `EXPIRED`
{.table-cell}
||
||

_subscriptionPlanId_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string&lt;uuid&gt;

ID of the subscription plan created in the dashboard or over the API.

_Example:_{.json-schema-reset .json-schema-example} `123e4567-e89b-12d3-a456-426614174000`
{.table-cell}
||
||

_nextWriteOff_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string&lt;date-time&gt;

Date of the next attempt to debit a subscription fee

_Example:_{.json-schema-reset .json-schema-example} `2025-01-01T00:00:00Z`
{.table-cell}
||
|#{.json-schema-properties}

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "customerSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
  "nextWriteOff": "2025-01-01T00:00:00Z",
  "status": "NEW",
  "subscriptionPlanId": "123e4567-e89b-12d3-a456-426614174000"
}
```

{% endcut %}

</div>

## Responses

<div class="openapi__response__code__200">

## 200 OK

success

<div class="openapi-entity">

### Body

{% cut "application/json" %}

```json translate=no
{
  "status": "success"
}
```

{% endcut %}

#|
|| **Name** | **Description** ||
||

_status_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

_Default:_{.json-schema-reset .json-schema-value} `success`
{.table-cell}
||
|#{.json-schema-properties}

</div>

</div>

<div class="openapi__response__code__400">

## 400 Bad Request

bad request

<div class="openapi-entity">

### Body

{% cut "application/json" %}

```json translate=no
{
  "reason": "example",
  "reasonCode": "FORBIDDEN",
  "status": "fail"
}
```

{% endcut %}

#|
|| **Name** | **Description** ||
||

_reasonCode_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

_Enum:_{.json-schema-reset .json-schema-value} `FORBIDDEN`, `ITEM_NOT_FOUND`, `ORDER_NOT_FOUND`, `ORDER_AMOUNT_MISMATCH`, `ORDER_DETAILS_MISMATCH`, `OUT_OF_INVENTORY`, `PICKUP_POINT_NOT_FOUND`, `SHIPPING_DETAILS_MISMATCH`, `OTHER`, `UNAUTHORIZED`, `TOKEN_EXPIRED`, `CONFLICT`
{.table-cell}
||
||

_reason_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_status_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

_Default:_{.json-schema-reset .json-schema-value} `fail`
{.table-cell}
||
|#{.json-schema-properties}

</div>

</div>

</div>
<!-- endsource: en/custom/backend/merchant-api-hidden/webhook.md -->


[*Deprecated]: No longer supported, please use an alternative and newer version.