Skip to Content
Вебхуки

Webhooks

Webhooks - это механизм, позволяющий вашему приложению получать уведомления о событиях, происходящих в системе CapitalPay. Когда происходит событие, система отправляет HTTP POST запрос на указанный вами URL с информацией о событии.

Вебхуки могут быть использованы для автоматизации процессов, таких как обновление статуса заказа, уведомление о новых платежах и т.д. Вы можете настроить вебхуки в личном кабинете CapitalPay или через запрос на создание заказа.

Вебхуки отправляются в случае изменения статуса заказа. Например, если заказ был успешно оплачен, система отправит вебхук на указанный вами URL с информацией о заказе и новом статусе.

Пример вебхука

Вебхуки оплаты (order.*)

POST https://your.webhook.url
 
Content-Type: application/json
Accept: application/json
Signature: {generated_hmac_signature}
 
{
  "event": "order.status.update",
  "data": {
    "order_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "cash_desk_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "external_order_id": 123456,
    "external_client_id": 123456,
    "external_data": "{\"key\": \"value\"}",
    "amount": 100.50,
    "refund_amount": 0,
    "currency_code": "KZT",
    "status_id": 3,
    "status": "Paid",
    "error_code": null,
    "error_message": null,
    "transaction_end_at": "2023-10-01T12:00:00Z",
    "title": "Order Title",
    "description": "Order Description",
    "recur_frequency": null,
    "recur_expired_at": null,
  }
}

Вебхуки подписки (subscription.*)

POST https://your.webhook.url
 
Content-Type: application/json
Accept: application/json
Signature: {generated_hmac_signature}
 
{
  "event": "subscription.status.update",
  "data": {
    "subscription_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "cash_desk_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "external_order_id": 123456,
    "external_client_id": 123456,
    "external_data": "{\"key\": \"value\"}",
    "amount": 100.50,
    "currency_code": "KZT",
    "status_id": 2,
    "status": "Active",
    "error_code": null,
    "error_message": null,
    "started_at": "2023-10-01T12:00:00Z",
    "title": "Order Title",
    "description": "Order Description",
    "frequency": 'weekly',
    "expired_at": "2027-12-31",
  }
}

Вебхуки токенов оплаты (card_token.*)

POST https://your.webhook.url
 
Content-Type: application/json
Accept: application/json
Signature: {generated_hmac_signature}
 
{
  "event": "card_token.create",
  "data": {
    "token_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "order_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "cash_desk_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "card_mask": "1234********3456",
    "external_order_id": null,
    "external_client_id": null,
    "external_data": null,
  }
}

В целях безопасности рекомендуется проверять подпись вебхука на принимающей стороне. Подпись создается аналогично подписи при создании заказа, но с использованием других полей.

Генерация подписи

Важно! Для генерации HMAC SHA256 подписи используйте секретный ключ API key который был использован при создании заказа/платежной ссылки.

Подпись создается с помощью HMAC SHA256 алгоритма. Подробней о работе с подписями можно прочитать в разделе Создание подписи. Для создания подписи необходимо использовать следующие поля в заданном порядке:

Вебхуки оплаты (order.*)

  • amount
  • currency_code
  • error_code
  • error_message
  • external_client_id
  • external_order_id
  • order_uuid
  • status
  • status_id

Пример строки для подписи:

{amount};{currency_code};{error_code};{error_message};{external_client_id};{external_order_id};{order_uuid};{status};{status_id};
100.50;KZT;0;Success;123456;123456;123e4567-e89b-12d3-a456-426614174000;success;1;

Вебхуки подписки (subscription.*)

  • amount
  • currency_code
  • error_code
  • error_message
  • external_client_id
  • external_order_id
  • status
  • status_id
  • subscription_uuid

Пример строки для подписи:

{amount};{currency_code};{error_code};{error_message};{external_client_id};{external_order_id};{status};{status_id};{subscription_uuid};
100.50;KZT;0;Success;123456;123456;success;1;123e4567-e89b-12d3-a456-426614174000;

Вебхуки токенов оплаты (card_token.*)

  • external_client_id
  • external_order_id
  • order_uuid
  • token_uuid

Пример строки для подписи:

{external_client_id};{external_order_id};{order_uuid};{token_uuid};
123456;123456;123e4567-e89b-12d3-a456-426614174000;123e4567-e89b-12d3-a456-426614174000;
ПодписьСтатусы