Создать подписку на вебхуки

POST/api/partner/v1/webhooks

Scope: cards:write

Регистрирует HTTPS-адрес и возвращает секрет подписи.

Секрет показывается ОДИН раз. Каждая доставка несёт X-Timestamp и X-Signature, где подпись — hex(HMAC-SHA256(secret, timestamp \n POST \n path \n body)), та же конструкция, которой вы подписываете запросы к нам, так что одна реализация покрывает оба направления. path — всё после хоста, включая query-строку: адрес подписки с ?tenant=42 подписывается вместе с ним.

Ответьте 2xx, чтобы подтвердить доставку. Любой другой ответ повторяется с паузами 1, 5, 15, 30 и 60 минут, после чего доставка прекращается.

Тело запроса

Поле	Тип	Обяз.	Описание
`event_types`	array<string>	нет	Не передавайте или оставьте пустым, чтобы получать все типы. Неизвестный тип отклоняется, а не тихо никогда не доставляется.
`url`	string	да	HTTPS-адрес. Обычный HTTP отклоняется: тело содержит идентификаторы операций и карт, а подпись доказывает, кто отправил, но не защищает от того, кто читает.

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

BODY='{"url":"https://partner.example.com/hooks/cards","event_types":["card.issued","card.issue_failed","card.topped_up","card.topup_failed","operation.needs_review"]}'
TS=$(date +%s)
SIG=$(printf '%s\n%s\n%s\n%s' "$TS" "POST" "/api/partner/v1/webhooks" "$BODY" \
  | openssl dgst -sha256 -hmac "$PP_SECRET" -hex | awk '{print $NF}')

curl -sS -X POST "https://api.plativputi.com/api/partner/v1/webhooks" \
  -H "X-Key-Id: $PP_KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

const res = await pp("POST", "/webhooks", {
  "url": "https://partner.example.com/hooks/cards",
  "event_types": [
    "card.issued",
    "card.issue_failed",
    "card.topped_up",
    "card.topup_failed",
    "operation.needs_review"
  ]
});

res = pp("POST", "/webhooks", body={
    "url": "https://partner.example.com/hooks/cards",
    "event_types": [
        "card.issued",
        "card.issue_failed",
        "card.topped_up",
        "card.topup_failed",
        "operation.needs_review",
    ],
})

$res = pp('POST', '/webhooks', [
    'url' => 'https://partner.example.com/hooks/cards',
    'event_types' => [
        'card.issued',
        'card.issue_failed',
        'card.topped_up',
        'card.topup_failed',
        'operation.needs_review',
    ],
]);

pp() — функция-обёртка с подписью из раздела Аутентификация и подпись.

Ответ

201 Created — CreatedWebhookDTO

Поле	Тип	Обяз.	Описание
`secret`	string	да	Секрет подписи доставок. Показывается один раз — сохраните сразу
`warning`	string	да	Напоминание, что секрет больше не покажут
`webhook`	WebhookDTO	да	Созданная подписка
`webhook.created_at`	string	да	Когда подписка создана, UTC
`webhook.event_types`	array<string>	да	Пусто — все типы событий
`webhook.id`	string	да	Идентификатор подписки
`webhook.is_active`	boolean	да	Идут ли доставки
`webhook.secret_last4`	string	да	Последние четыре символа секрета подписи
`webhook.url`	string	да	Адрес доставки

Примеры ответа

{
  "webhook": {
    "id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
    "url": "https://partner.example.com/hooks/cards",
    "event_types": [
      "card.issued",
      "card.issue_failed",
      "card.topped_up",
      "card.topup_failed",
      "operation.needs_review"
    ],
    "is_active": true,
    "secret_last4": "9f3a",
    "created_at": "2026-10-07T09:00:00Z"
  },
  "secret": "q3Vx8LmT2bR7kJ0pWz5NcY1hFd6sGa4EiUo9Pn_9f3a",
  "warning": "Секрет показывается один раз. Сохраните его сейчас — восстановить нельзя, только создать новую подписку."
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "validation: url must use https",
  "errors": [
    {
      "message": "validation_failed",
      "location": "error.code",
      "value": "validation_failed"
    }
  ]
}

Ошибки

HTTP	Код	Когда
400	`validation_failed`	Адрес не HTTPS или в `event_types` неизвестный тип события.

Плюс общие ошибки подписи и лимитов — см. Ошибки.