Webhooks

Endpoints для настройки webhook URL, проверки доставки событий и повторной отправки failed deliveries.

Webhook secret отличается от API HMAC secret. API secret подписывает исходящие запросы вашего приложения к API, а webhook secret нужен вам для проверки входящих событий от обменника.

Список webhooks

List webhook endpoints

get

Required scopes

This endpoint requires the following scopes:

Authorizations

sanctumBearer

AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Responses

200

Webhook endpoint list and event catalog.

application/json

stateinteger · enumRequiredPossible values:

messagestringRequired

403

Standard error envelope.

application/json

get/private/webhooks

HTTPcURLJavaScriptPython

GET /api/v3/private/webhooks HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "state": 0,
  "message": "text",
  "result": {
    "endpoints": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "url": "https://example.com",
        "events": [
          "text"
        ],
        "status": "active",
        "signing_algorithm": "hmac-sha256-v1",
        "secret_fingerprint": "text",
        "failure_count": 1,
        "last_delivery_at": "2026-07-17T04:26:40.084Z",
        "last_success_at": "2026-07-17T04:26:40.084Z",
        "last_failure_at": "2026-07-17T04:26:40.084Z",
        "created_at": "2026-07-17T04:26:40.084Z",
        "updated_at": "2026-07-17T04:26:40.084Z"
      }
    ],
    "events": [
      {
        "event": "order.status_changed",
        "title": "text"
      }
    ],
    "limits": {}
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-07-17T04:26:40.084Z",
    "pagination": {
      "mode": "page",
      "current_page": 1,
      "per_page": 1,
      "total": 1,
      "last_page": 1,
      "from": 1,
      "to": 1,
      "cursor": "text",
      "next_cursor": "text",
      "has_more": true
    }
  }
}

Создать webhook

Create webhook endpoint

post

Required scopes

This endpoint requires the following scopes:

Authorizations

sanctumBearer

AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Header parameters

Idempotency-Keystring · min: 8 · max: 191Optional

Makes unsafe requests safely repeatable for 24 hours by default.

X-Correlation-Idstring · max: 128Optional

Client-defined id used to correlate API request and webhook events.

Body

application/json

namestring · max: 80Required

urlstring · uri · max: 500Required

eventsstring[] · min: 1Required

Responses

201

Webhook endpoint with one-time secret.

application/json

stateinteger · enumRequiredPossible values:

messagestringRequired

409

Standard error envelope.

application/json

422

Standard error envelope.

application/json

post/private/webhooks

HTTPcURLJavaScriptPython

POST /api/v3/private/webhooks HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "name": "text",
  "url": "https://example.com",
  "events": [
    "text"
  ]
}

{
  "state": 0,
  "message": "text",
  "result": {
    "endpoint": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "url": "https://example.com",
      "events": [
        "text"
      ],
      "status": "active",
      "signing_algorithm": "hmac-sha256-v1",
      "secret_fingerprint": "text",
      "failure_count": 1,
      "last_delivery_at": "2026-07-17T04:26:40.084Z",
      "last_success_at": "2026-07-17T04:26:40.084Z",
      "last_failure_at": "2026-07-17T04:26:40.084Z",
      "created_at": "2026-07-17T04:26:40.084Z",
      "updated_at": "2026-07-17T04:26:40.084Z",
      "secret": "text"
    }
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-07-17T04:26:40.084Z",
    "pagination": {
      "mode": "page",
      "current_page": 1,
      "per_page": 1,
      "total": 1,
      "last_page": 1,
      "from": 1,
      "to": 1,
      "cursor": "text",
      "next_cursor": "text",
      "has_more": true
    }
  }
}

Проверить webhook

Create a test webhook event

post

Required scopes

This endpoint requires the following scopes:

Authorizations

sanctumBearer

AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Header parameters

Idempotency-Keystring · min: 8 · max: 191Optional

Makes unsafe requests safely repeatable for 24 hours by default.

X-Correlation-Idstring · max: 128Optional

Client-defined id used to correlate API request and webhook events.

Body

application/json

endpoint_idstring · uuid · nullableOptional

event_typestringOptionalExample: api.test

Responses

201

Created webhook event and delivery ids.

application/json

stateinteger · enumRequiredPossible values:

messagestringRequired

409

Standard error envelope.

application/json

422

Standard error envelope.

application/json

post/private/webhooks/test

HTTPcURLJavaScriptPython

POST /api/v3/private/webhooks/test HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 127

{
  "endpoint_id": "123e4567-e89b-12d3-a456-426614174000",
  "event_type": "api.test",
  "payload": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "state": 0,
  "message": "text",
  "result": {
    "event": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "text",
      "status": "text",
      "request_id": "text",
      "correlation_id": "text"
    },
    "deliveries": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "status": "text",
        "endpoint_id": "123e4567-e89b-12d3-a456-426614174000"
      }
    ]
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-07-17T04:26:40.084Z",
    "pagination": {
      "mode": "page",
      "current_page": 1,
      "per_page": 1,
      "total": 1,
      "last_page": 1,
      "from": 1,
      "to": 1,
      "cursor": "text",
      "next_cursor": "text",
      "has_more": true
    }
  }
}

Список webhook events

List webhook events

get

Required scopes

This endpoint requires the following scopes:

Authorizations

sanctumBearer

AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Query parameters

pageinteger · min: 1OptionalDefault: 1

per_pageinteger · min: 1 · max: 100OptionalDefault: 25

paginationstring · enumOptional

Use cursor for large datasets. The first cursor page uses pagination=cursor; next pages use cursor.

Default: pagePossible values:

cursorstring · nullableOptional

Opaque cursor returned in meta.pagination.next_cursor.

filter[status]stringOptional

filter[event_type]stringOptional

filter[resource_type]stringOptional

filter[resource_id]stringOptional

filter[correlation_id]stringOptional

filter[created_from]string · date-timeOptional

filter[created_to]string · date-timeOptional

Responses

200

Webhook event list.

application/json

stateinteger · enumRequiredPossible values:

messagestringRequired

403

Standard error envelope.

application/json

get/private/webhooks/events

HTTPcURLJavaScriptPython

GET /api/v3/private/webhooks/events HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "state": 0,
  "message": "text",
  "result": {
    "events": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "order.created",
        "resource": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "status": "text",
        "request_id": "text",
        "correlation_id": "text",
        "idempotency_key": "text",
        "payload": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "deliveries_count": 1,
        "deliveries": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "status": "queued",
            "attempt": 1,
            "endpoint": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "event": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "request": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "response": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "error": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "next_retry_at": "2026-07-17T04:26:40.084Z",
            "delivered_at": "2026-07-17T04:26:40.084Z"
          }
        ],
        "created_at": "2026-07-17T04:26:40.084Z"
      }
    ]
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-07-17T04:26:40.084Z",
    "pagination": {
      "mode": "page",
      "current_page": 1,
      "per_page": 1,
      "total": 1,
      "last_page": 1,
      "from": 1,
      "to": 1,
      "cursor": "text",
      "next_cursor": "text",
      "has_more": true
    }
  }
}

Получить webhook event

Show webhook event

get

Required scopes

This endpoint requires the following scopes:

Authorizations

sanctumBearer

AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Path parameters

eventstring · uuidRequired

Responses

200

Webhook event with deliveries.

application/json

stateinteger · enumRequiredPossible values:

messagestringRequired

404

Standard error envelope.

application/json

get/private/webhooks/events/{event}

HTTPcURLJavaScriptPython

GET /api/v3/private/webhooks/events/{event} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "state": 0,
  "message": "text",
  "result": {
    "event": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "order.created",
      "resource": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "status": "text",
      "request_id": "text",
      "correlation_id": "text",
      "idempotency_key": "text",
      "payload": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "deliveries_count": 1,
      "deliveries": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "status": "queued",
          "attempt": 1,
          "endpoint": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "event": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "request": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "response": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "error": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "next_retry_at": "2026-07-17T04:26:40.084Z",
          "delivered_at": "2026-07-17T04:26:40.084Z"
        }
      ],
      "created_at": "2026-07-17T04:26:40.084Z"
    }
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-07-17T04:26:40.084Z",
    "pagination": {
      "mode": "page",
      "current_page": 1,
      "per_page": 1,
      "total": 1,
      "last_page": 1,
      "from": 1,
      "to": 1,
      "cursor": "text",
      "next_cursor": "text",
      "has_more": true
    }
  }
}

Список доставок

List webhook delivery attempts

get

Required scopes

This endpoint requires the following scopes:

Authorizations

sanctumBearer

AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Query parameters

pageinteger · min: 1OptionalDefault: 1

per_pageinteger · min: 1 · max: 100OptionalDefault: 25

paginationstring · enumOptional

Use cursor for large datasets. The first cursor page uses pagination=cursor; next pages use cursor.

Default: pagePossible values:

cursorstring · nullableOptional

Opaque cursor returned in meta.pagination.next_cursor.

filter[status]stringOptional

filter[endpoint_id]string · uuidOptional

filter[event_id]string · uuidOptional

filter[event_type]stringOptional

filter[correlation_id]stringOptional

filter[created_from]string · date-timeOptional

filter[created_to]string · date-timeOptional

Responses

200

Webhook delivery list.

application/json

stateinteger · enumRequiredPossible values:

messagestringRequired

403

Standard error envelope.

application/json

get/private/webhooks/deliveries

HTTPcURLJavaScriptPython

GET /api/v3/private/webhooks/deliveries HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "state": 0,
  "message": "text",
  "result": {
    "deliveries": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "status": "queued",
        "attempt": 1,
        "endpoint": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "event": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "request": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "response": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "error": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "next_retry_at": "2026-07-17T04:26:40.084Z",
        "delivered_at": "2026-07-17T04:26:40.084Z"
      }
    ]
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-07-17T04:26:40.084Z",
    "pagination": {
      "mode": "page",
      "current_page": 1,
      "per_page": 1,
      "total": 1,
      "last_page": 1,
      "from": 1,
      "to": 1,
      "cursor": "text",
      "next_cursor": "text",
      "has_more": true
    }
  }
}

Получить доставку

Show webhook delivery attempt

get

Required scopes

This endpoint requires the following scopes:

Authorizations

sanctumBearer

AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Path parameters

deliverystring · uuidRequired

Responses

200

Webhook delivery.

application/json

stateinteger · enumRequiredPossible values:

messagestringRequired

404

Standard error envelope.

application/json

get/private/webhooks/deliveries/{delivery}

HTTPcURLJavaScriptPython

GET /api/v3/private/webhooks/deliveries/{delivery} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "state": 0,
  "message": "text",
  "result": {
    "delivery": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "queued",
      "attempt": 1,
      "endpoint": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "event": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "request": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "response": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "error": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "next_retry_at": "2026-07-17T04:26:40.084Z",
      "delivered_at": "2026-07-17T04:26:40.084Z"
    }
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-07-17T04:26:40.084Z",
    "pagination": {
      "mode": "page",
      "current_page": 1,
      "per_page": 1,
      "total": 1,
      "last_page": 1,
      "from": 1,
      "to": 1,
      "cursor": "text",
      "next_cursor": "text",
      "has_more": true
    }
  }
}

Повторить доставку

Retry webhook delivery attempt

post

Required scopes

This endpoint requires the following scopes:

Authorizations

sanctumBearer

AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Path parameters

deliverystring · uuidRequired

Header parameters

Idempotency-Keystring · min: 8 · max: 191Optional

Makes unsafe requests safely repeatable for 24 hours by default.

X-Correlation-Idstring · max: 128Optional

Client-defined id used to correlate API request and webhook events.

Responses

200

Delivery queued for retry.

application/json

stateinteger · enumRequiredPossible values:

messagestringRequired

404

Standard error envelope.

application/json

409

Standard error envelope.

application/json

post/private/webhooks/deliveries/{delivery}/retry

HTTPcURLJavaScriptPython

POST /api/v3/private/webhooks/deliveries/{delivery}/retry HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "state": 0,
  "message": "text",
  "result": {
    "delivery": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "queued",
      "attempt": 1,
      "endpoint": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "event": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "request": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "response": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "error": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "next_retry_at": "2026-07-17T04:26:40.084Z",
      "delivered_at": "2026-07-17T04:26:40.084Z"
    }
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-07-17T04:26:40.084Z",
    "pagination": {
      "mode": "page",
      "current_page": 1,
      "per_page": 1,
      "total": 1,
      "last_page": 1,
      "from": 1,
      "to": 1,
      "cursor": "text",
      "next_cursor": "text",
      "has_more": true
    }
  }
}

Получить webhook

Show webhook endpoint

get

Required scopes

This endpoint requires the following scopes:

Authorizations

sanctumBearer

AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Path parameters

webhookstring · uuidRequired

Responses

200

Standard success envelope.

application/json

stateinteger · enumRequiredPossible values:

messagestringRequired

resultany · nullableRequired

404

Standard error envelope.

application/json

get/private/webhooks/{webhook}

HTTPcURLJavaScriptPython

GET /api/v3/private/webhooks/{webhook} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "state": 0,
  "message": "text",
  "result": null,
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-07-17T04:26:40.084Z",
    "pagination": {
      "mode": "page",
      "current_page": 1,
      "per_page": 1,
      "total": 1,
      "last_page": 1,
      "from": 1,
      "to": 1,
      "cursor": "text",
      "next_cursor": "text",
      "has_more": true
    }
  }
}

Обновить webhook

Update webhook endpoint

patch

Required scopes

This endpoint requires the following scopes:

Authorizations

sanctumBearer

AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Path parameters

webhookstring · uuidRequired

Header parameters

Idempotency-Keystring · min: 8 · max: 191Optional

Makes unsafe requests safely repeatable for 24 hours by default.

X-Correlation-Idstring · max: 128Optional

Client-defined id used to correlate API request and webhook events.

Body

application/json

namestring · max: 80Optional

urlstring · uri · max: 500Optional

eventsstring[] · min: 1Optional

statusstring · enumOptionalPossible values:

Responses

200

Standard success envelope.

application/json

stateinteger · enumRequiredPossible values:

messagestringRequired

resultany · nullableRequired

404

Standard error envelope.

application/json

409

Standard error envelope.

application/json

422

Standard error envelope.

application/json

patch/private/webhooks/{webhook}

HTTPcURLJavaScriptPython

PATCH /api/v3/private/webhooks/{webhook} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 79

{
  "name": "text",
  "url": "https://example.com",
  "events": [
    "text"
  ],
  "status": "active"
}

{
  "state": 0,
  "message": "text",
  "result": null,
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-07-17T04:26:40.084Z",
    "pagination": {
      "mode": "page",
      "current_page": 1,
      "per_page": 1,
      "total": 1,
      "last_page": 1,
      "from": 1,
      "to": 1,
      "cursor": "text",
      "next_cursor": "text",
      "has_more": true
    }
  }
}

Удалить webhook

Delete webhook endpoint

delete

Required scopes

This endpoint requires the following scopes:

Authorizations

sanctumBearer

AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Path parameters

webhookstring · uuidRequired

Header parameters

Idempotency-Keystring · min: 8 · max: 191Optional

Makes unsafe requests safely repeatable for 24 hours by default.

X-Correlation-Idstring · max: 128Optional

Client-defined id used to correlate API request and webhook events.

Responses

200

Standard success envelope.

application/json

stateinteger · enumRequiredPossible values:

messagestringRequired

resultany · nullableRequired

404

Standard error envelope.

application/json

409

Standard error envelope.

application/json

delete/private/webhooks/{webhook}

HTTPcURLJavaScriptPython

DELETE /api/v3/private/webhooks/{webhook} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "state": 0,
  "message": "text",
  "result": null,
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-07-17T04:26:40.084Z",
    "pagination": {
      "mode": "page",
      "current_page": 1,
      "per_page": 1,
      "total": 1,
      "last_page": 1,
      "from": 1,
      "to": 1,
      "cursor": "text",
      "next_cursor": "text",
      "has_more": true
    }
  }
}

Сменить webhook secret

Rotate webhook signing secret

post

Required scopes

This endpoint requires the following scopes:

Authorizations

sanctumBearer

AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Path parameters

webhookstring · uuidRequired

Header parameters

Idempotency-Keystring · min: 8 · max: 191Optional

Makes unsafe requests safely repeatable for 24 hours by default.

X-Correlation-Idstring · max: 128Optional

Client-defined id used to correlate API request and webhook events.

Responses

200

Webhook endpoint with one-time new secret.

application/json

stateinteger · enumRequiredPossible values:

messagestringRequired

404

Standard error envelope.

application/json

409

Standard error envelope.

application/json

post/private/webhooks/{webhook}/rotate-secret

HTTPcURLJavaScriptPython

POST /api/v3/private/webhooks/{webhook}/rotate-secret HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "state": 0,
  "message": "text",
  "result": {
    "endpoint": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "url": "https://example.com",
      "events": [
        "text"
      ],
      "status": "active",
      "signing_algorithm": "hmac-sha256-v1",
      "secret_fingerprint": "text",
      "failure_count": 1,
      "last_delivery_at": "2026-07-17T04:26:40.084Z",
      "last_success_at": "2026-07-17T04:26:40.084Z",
      "last_failure_at": "2026-07-17T04:26:40.084Z",
      "created_at": "2026-07-17T04:26:40.084Z",
      "updated_at": "2026-07-17T04:26:40.084Z",
      "secret": "text"
    }
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-07-17T04:26:40.084Z",
    "pagination": {
      "mode": "page",
      "current_page": 1,
      "per_page": 1,
      "total": 1,
      "last_page": 1,
      "from": 1,
      "to": 1,
      "cursor": "text",
      "next_cursor": "text",
      "has_more": true
    }
  }
}