Вебхуки

Download schema

Адреса, на которые мы сами отправляем события

Список вебхуков

GET

https://partners.zvezdnyy-burabai.edu.kz/ext/v1

/webhooks

Все вебхуки подключения, включая отключённые.

Список вебхуков › query Parameters

cursor

string

Курсор из next_cursor прошлого ответа

limit

integer · int64 · min: 1 · max: 200

Сколько записей вернуть, 1–200, по умолчанию 50

Default: 50

Список вебхуков › Responses

Готово

Порция списка. `next_cursor` пуст — дальше ничего нет.

Page_Webhook

Webhook[] · required

next_cursor

string | null

Передать в cursor, чтобы получить следующую порцию

Создать вебхук

POST

https://partners.zvezdnyy-burabai.edu.kz/ext/v1

/webhooks

Мы будем отправлять события вашего отдела на этот адрес: POST, тело — событие в том же виде, что в GET /events, по одному за запрос, строго по порядку номеров. Следующее событие уходит, только когда вы ответили 2xx на предыдущее.

Ответ несёт secret — ключ подписи whsec_…. Он показывается один раз: сохраните его. Потеряли — смените (rotate-secret).

Адрес: только https:// с действующим сертификатом, публичный (внутренние и служебные адреса отклоняются), без логина и пароля в адресе. Переадресации не выполняются. Живых вебхуков — до 5.

Проверка подписи — в разделе «Вебхуки» описания API.

Создать вебхук › Headers

Idempotency-Key

string · required

Своя случайная строка на каждое действие

Создать вебхук › Request Body

CreateWebhook

url

string · required

Только https://, публичный адрес, без логина и #

event_types

array | null

Только эти типы событий: любые из Event.type, кроме ping (он приходит только на проверку). Незнакомый тип — отказ bad_event_type. Нет или пусто — все, включая будущие

Создать вебхук › Responses

Создан; secret — только в этом ответе

Webhook

created_at

string · date-time · required

delivered_through

string · required

Номер последнего доставленного события

enabled

boolean · required

false — отключён (вами или после трёх суток неудач)

event_types

string[] · required

Какие типы событий слать (см. Event.type). Пусто — все

failed_attempts

integer · int32 · required

Неудачных попыток подряд

id

string · required

url

string · required

disabled_reason

string | null

Почему отключён

failing_since

string | null · date-time

С какого момента адрес не принимает события подряд

next_attempt_at

string | null · date-time

Когда следующая попытка после неудачи

secret

string | null

Секрет подписи whsec_…. Только в ответе на создание и смену секрета — сохраните его сразу: больше его не покажут

POST/webhooks

curl https://partners.zvezdnyy-burabai.edu.kz/ext/v1/webhooks \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "event_types": [
    "string"
  ],
  "url": "https://crm.example.kz/hooks/camp"
}'

Example Request Body

{
  "event_types": [
    "string"
  ],
  "url": "https://crm.example.kz/hooks/camp"
}

json

Example Responses

{
  "created_at": "2024-08-25T15:00:00Z",
  "delivered_through": "1042",
  "disabled_reason": "disabled_reason",
  "enabled": true,
  "event_types": [
    "string"
  ],
  "failed_attempts": 0,
  "failing_since": "2024-08-25T15:00:00Z",
  "id": "7",
  "next_attempt_at": "2024-08-25T15:00:00Z",
  "secret": "secret",
  "url": "https://crm.example.kz/hooks/camp"
}

json

application/json

Вебхук

GET

https://partners.zvezdnyy-burabai.edu.kz/ext/v1

/webhooks/{id}

Вебхук › path Parameters

id

string · required

Номер вебхука

Вебхук › Responses

Готово

Webhook

created_at

string · date-time · required

delivered_through

string · required

Номер последнего доставленного события

enabled

boolean · required

false — отключён (вами или после трёх суток неудач)

event_types

string[] · required

Какие типы событий слать (см. Event.type). Пусто — все

failed_attempts

integer · int32 · required

Неудачных попыток подряд

id

string · required

url

string · required

disabled_reason

string | null

Почему отключён

failing_since

string | null · date-time

С какого момента адрес не принимает события подряд

next_attempt_at

string | null · date-time

Когда следующая попытка после неудачи

secret

string | null

Изменить вебхук

PATCH

https://partners.zvezdnyy-burabai.edu.kz/ext/v1

/webhooks/{id}

Адрес, типы событий, включение. Включение снова сбрасывает счёт неудач, и доставка продолжается с места, где остановилась.

Изменить вебхук › path Parameters

id

string · required

Номер вебхука

Изменить вебхук › Request Body

PatchWebhook

enabled

boolean | null

false — отключить, true — включить (сбрасывает счёт неудач)

event_types

array | null

Типы событий, как у CreateWebhook.event_types. Пустой список — все типы

url

string | null

Изменить вебхук › Responses

Готово

Webhook

created_at

string · date-time · required

delivered_through

string · required

Номер последнего доставленного события

enabled

boolean · required

false — отключён (вами или после трёх суток неудач)

event_types

string[] · required

Какие типы событий слать (см. Event.type). Пусто — все

failed_attempts

integer · int32 · required

Неудачных попыток подряд

id

string · required

url

string · required

disabled_reason

string | null

Почему отключён

failing_since

string | null · date-time

С какого момента адрес не принимает события подряд

next_attempt_at

string | null · date-time

Когда следующая попытка после неудачи

secret

string | null

PATCH/webhooks/{id}

curl https://partners.zvezdnyy-burabai.edu.kz/ext/v1/webhooks/:id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "enabled": true,
  "event_types": [
    "string"
  ],
  "url": "url"
}'

Example Request Body

{
  "enabled": true,
  "event_types": [
    "string"
  ],
  "url": "url"
}

json

Example Responses

{
  "created_at": "2024-08-25T15:00:00Z",
  "delivered_through": "1042",
  "disabled_reason": "disabled_reason",
  "enabled": true,
  "event_types": [
    "string"
  ],
  "failed_attempts": 0,
  "failing_since": "2024-08-25T15:00:00Z",
  "id": "7",
  "next_attempt_at": "2024-08-25T15:00:00Z",
  "secret": "secret",
  "url": "https://crm.example.kz/hooks/camp"
}

json

application/json

Отключить вебхук

DELETE

https://partners.zvezdnyy-burabai.edu.kz/ext/v1

/webhooks/{id}

Вебхук не удаляется: он остаётся в списке отключённым вместе с журналом доставок, и его можно включить снова (PATCH, enabled).

Отключить вебхук › path Parameters

id

string · required

Номер вебхука

Отключить вебхук › Responses

Готово

Webhook

created_at

string · date-time · required

delivered_through

string · required

Номер последнего доставленного события

enabled

boolean · required

false — отключён (вами или после трёх суток неудач)

event_types

string[] · required

Какие типы событий слать (см. Event.type). Пусто — все

failed_attempts

integer · int32 · required

Неудачных попыток подряд

id

string · required

url

string · required

disabled_reason

string | null

Почему отключён

failing_since

string | null · date-time

С какого момента адрес не принимает события подряд

next_attempt_at

string | null · date-time

Когда следующая попытка после неудачи

secret

string | null

Журнал доставок

GET

https://partners.zvezdnyy-burabai.edu.kz/ext/v1

/webhooks/{id}/deliveries

Попытки отправки на этот вебхук, от новых к старым, за 30 дней.

Журнал доставок › path Parameters

id

string · required

Номер вебхука

Журнал доставок › query Parameters

cursor

string

Курсор из next_cursor прошлого ответа

limit

integer · int64 · min: 1 · max: 200

Сколько записей вернуть, 1–200, по умолчанию 50

Default: 50

Журнал доставок › Responses

Готово

Порция списка. `next_cursor` пуст — дальше ничего нет.

Page_Delivery

Delivery[] · required

next_cursor

string | null

Передать в cursor, чтобы получить следующую порцию

Отправить ещё раз

POST

https://partners.zvezdnyy-burabai.edu.kz/ext/v1

/webhooks/{id}/redeliver

Переставляет место доставки: всё ПОСЛЕ after будет отправлено заново, по порядку, в ближайшие секунды. Счёт неудач не трогается, но пауза до следующей попытки снимается. События хранятся 90 дней.

Отправить ещё раз › path Parameters

id

string · required

Номер вебхука

Отправить ещё раз › Headers

Idempotency-Key

string · required

Своя случайная строка на каждое действие

Отправить ещё раз › Request Body

Redeliver

after

string · required

Отправить заново всё ПОСЛЕ этого номера события. Номер меньше доставленного — повтор, больше — пропуск

Отправить ещё раз › Responses

Готово

Webhook

created_at

string · date-time · required

delivered_through

string · required

Номер последнего доставленного события

enabled

boolean · required

false — отключён (вами или после трёх суток неудач)

event_types

string[] · required

Какие типы событий слать (см. Event.type). Пусто — все

failed_attempts

integer · int32 · required

Неудачных попыток подряд

id

string · required

url

string · required

disabled_reason

string | null

Почему отключён

failing_since

string | null · date-time

С какого момента адрес не принимает события подряд

next_attempt_at

string | null · date-time

Когда следующая попытка после неудачи

secret

string | null

Сменить секрет подписи

POST

https://partners.zvezdnyy-burabai.edu.kz/ext/v1

/webhooks/{id}/rotate-secret

Новый секрет — в ответе, один раз. Старый перестаёт действовать сразу: события, отправленные после ответа, подписаны новым. Поэтому на время смены принимайте подпись любым из двух секретов, а старый удалите, когда пришло первое событие с новой подписью.

Сменить секрет подписи › path Parameters

id

string · required

Номер вебхука

Сменить секрет подписи › Headers

Idempotency-Key

string · required

Своя случайная строка на каждое действие

Сменить секрет подписи › Responses

Новый secret — только в этом ответе

Webhook

created_at

string · date-time · required

delivered_through

string · required

Номер последнего доставленного события

enabled

boolean · required

false — отключён (вами или после трёх суток неудач)

event_types

string[] · required

Какие типы событий слать (см. Event.type). Пусто — все

failed_attempts

integer · int32 · required

Неудачных попыток подряд

id

string · required

url

string · required

disabled_reason

string | null

Почему отключён

failing_since

string | null · date-time

С какого момента адрес не принимает события подряд

next_attempt_at

string | null · date-time

Когда следующая попытка после неудачи

secret

string | null

Проверить адрес

POST

https://partners.zvezdnyy-burabai.edu.kz/ext/v1

/webhooks/{id}/test

Сразу отправляет на адрес вебхука событие ping (номер 0, сущность webhook) с настоящей подписью и возвращает, что ответил ваш сервер. Попытка попадает в журнал доставок. Работает и для отключённого вебхука — удобно проверить адрес перед включением. Ничего не меняет, поэтому Idempotency-Key не нужен (если передан — не учитывается: каждый вызов отправляет новый ping).

Проверить адрес › path Parameters

id

string · required

Номер вебхука

Проверить адрес › Responses

Результат отправки (в том числе неудачной)

TestResult

duration_ms

integer · int32 · required

ok

boolean · required

Адрес ответил 2xx

error

string | null

status

integer | null · int32 · min: 0

Код ответа; нет — ответа не было (DNS, соединение, сертификат, время)

Отчёты