Ctrlk
ДемоОфициальный сайт
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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
AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Responses
200

Webhook endpoint list and event catalog.

application/json
stateinteger · enumRequiredPossible values:
messagestringRequired
get/private/webhooks
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-01-01T00:00:00.000Z",
        "last_success_at": "2026-01-01T00:00:00.000Z",
        "last_failure_at": "2026-01-01T00:00:00.000Z",
        "created_at": "2026-01-01T00:00:00.000Z",
        "updated_at": "2026-01-01T00:00:00.000Z"
      }
    ],
    "events": [
      {
        "event": "order.status_changed",
        "title": "text"
      }
    ],
    "limits": {}
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-01-01T00:00:00.000Z",
    "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
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
namestring · max: 80Required
urlstring · uri · max: 500Required
eventsstring[] · min: 1Required
Responses
201

Webhook endpoint with one-time secret.

application/json
stateinteger · enumRequiredPossible values:
messagestringRequired
post/private/webhooks
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-01-01T00:00:00.000Z",
      "last_success_at": "2026-01-01T00:00:00.000Z",
      "last_failure_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "secret": "text"
    }
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-01-01T00:00:00.000Z",
    "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
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
endpoint_idstring · uuid · nullableOptional
event_typestringOptionalExample: api.test
Responses
201

Created webhook event and delivery ids.

application/json
stateinteger · enumRequiredPossible values:
messagestringRequired
post/private/webhooks/test
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-01-01T00:00:00.000Z",
    "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
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
get/private/webhooks/events
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-01-01T00:00:00.000Z",
            "delivered_at": "2026-01-01T00:00:00.000Z"
          }
        ],
        "created_at": "2026-01-01T00:00:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-01-01T00:00:00.000Z",
    "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
AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Path parameters
eventstring · uuidRequired
Responses
200

Webhook event with deliveries.

application/json
stateinteger · enumRequiredPossible values:
messagestringRequired
get/private/webhooks/events/{event}
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-01-01T00:00:00.000Z",
          "delivered_at": "2026-01-01T00:00:00.000Z"
        }
      ],
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-01-01T00:00:00.000Z",
    "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
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
get/private/webhooks/deliveries
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-01-01T00:00:00.000Z",
        "delivered_at": "2026-01-01T00:00:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-01-01T00:00:00.000Z",
    "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
AuthorizationstringRequired

Sanctum token in Authorization: Bearer <token> format.

Path parameters
deliverystring · uuidRequired
Responses
200

Webhook delivery.

application/json
stateinteger · enumRequiredPossible values:
messagestringRequired
get/private/webhooks/deliveries/{delivery}
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-01-01T00:00:00.000Z",
      "delivered_at": "2026-01-01T00:00:00.000Z"
    }
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-01-01T00:00:00.000Z",
    "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
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
post/private/webhooks/deliveries/{delivery}/retry
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-01-01T00:00:00.000Z",
      "delivered_at": "2026-01-01T00:00:00.000Z"
    }
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-01-01T00:00:00.000Z",
    "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
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
get/private/webhooks/{webhook}
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-01-01T00:00:00.000Z",
    "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
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
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
patch/private/webhooks/{webhook}
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-01-01T00:00:00.000Z",
    "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
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
delete/private/webhooks/{webhook}
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-01-01T00:00:00.000Z",
    "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
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
post/private/webhooks/{webhook}/rotate-secret
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-01-01T00:00:00.000Z",
      "last_success_at": "2026-01-01T00:00:00.000Z",
      "last_failure_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "secret": "text"
    }
  },
  "meta": {
    "request_id": "text",
    "correlation_id": "text",
    "timestamp": "2026-01-01T00:00:00.000Z",
    "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
    }
  }
}
ПредыдущаяVerifications
СледующаяPartner

Последнее обновление

Это было полезно?