Webhooks

List of webhooks

All webhooks of the key’s organization: URL, channels, whether enabled, how many deliveries are pending, the last successful delivery and the last error. Signing secrets are not included. From the “API.Max Growth” plan, 0 units.

Response fields

Field	Type	Description
results	list	Webhooks of the key’s organization
results[].id	number	Webhook number — in /v1/max/webhooks/{id}/ URLs and in events
results[].url	string	The address events are sent to (https://)
results[].is_active	yes / no	Whether the webhook is enabled
results[].disabled_reason	string	Why it is disabled: failing — no successful delivery for a day, client — disabled by you, staff — by datool.ru staff; empty — enabled
results[].channels	list	Numbers of the subscribed MAX channels
results[].pending	number	Deliveries waiting to be sent
results[].created_at	date and time	When the webhook was created (ISO 8601, Moscow time)
results[].last_success_at	date and time or null	Last successful delivery
results[].failing_since	date and time or null	Since when there have been no successful deliveries; null — all good
results[].last_error	string	The last delivery error, briefly

Errors

Code	code	When
401	not_authenticated / authentication_failed	No key, the key is wrong or revoked, the member is suspended or the key’s organization is archived.
403	tariff_required	Webhooks are available from the “API.Max Growth” plan.
429	rate_limited / throttled	Too often — more requests per second than your plan allows; how long to wait is in the Retry-After header.

Create a webhook

A new webhook: post.created events about new posts in these channels will be sent to the address as POST requests. The signing secret is in the response and is shown only once.

Request body

JSON with the Content-Type: application/json header.

Field	Type	Description
url	string	The https:// address events are sent to
channels	list	datool.ru numbers of public MAX channels (the id field in the catalog)

Response fields

Field	Type	Description
id	number	Webhook number — in /v1/max/webhooks/{id}/ URLs and in events
url	string	The address events are sent to (https://)
is_active	yes / no	Whether the webhook is enabled
disabled_reason	string	Why it is disabled: failing — no successful delivery for a day, client — disabled by you, staff — by datool.ru staff; empty — enabled
channels	list	Numbers of the subscribed MAX channels
pending	number	Deliveries waiting to be sent
created_at	date and time	When the webhook was created (ISO 8601, Moscow time)
last_success_at	date and time or null	Last successful delivery
failing_since	date and time or null	Since when there have been no successful deliveries; null — all good
last_error	string	The last delivery error, briefly
secret	string	The X-Datool-Signature signing secret. Shown only once — save it

Errors

Code	code	When
400	field errors	An invalid parameter or body field: the error comes under the field name, for example {"channels": ["Comma-separated channel numbers."]}.
401	not_authenticated / authentication_failed	No key, the key is wrong or revoked, the member is suspended or the key’s organization is archived.
403	tariff_required	Webhooks are available from the “API.Max Growth” plan.
403	read_only_key	The key has no “read and write” mark.
403	manager_required	A member’s key: webhooks can be changed by the owner or an administrator.
403	limit_reached	You already have as many webhooks as your plan allows.
429	rate_limited / throttled	Too often — more requests per second than your plan allows; how long to wait is in the Retry-After header.
503	timeout	The database query took longer than 5 seconds — retry later or narrow the selection.

Webhook

One webhook of the organization: channels, state, pending deliveries, the last successful delivery and error. Another organization’s webhook — 404.

Parameters

Name	Where	Description
id required number	path	Webhook number

Response fields

Field	Type	Description
id	number	Webhook number — in /v1/max/webhooks/{id}/ URLs and in events
url	string	The address events are sent to (https://)
is_active	yes / no	Whether the webhook is enabled
disabled_reason	string	Why it is disabled: failing — no successful delivery for a day, client — disabled by you, staff — by datool.ru staff; empty — enabled
channels	list	Numbers of the subscribed MAX channels
pending	number	Deliveries waiting to be sent
created_at	date and time	When the webhook was created (ISO 8601, Moscow time)
last_success_at	date and time or null	Last successful delivery
failing_since	date and time or null	Since when there have been no successful deliveries; null — all good
last_error	string	The last delivery error, briefly

Errors

Code	code	When
401	not_authenticated / authentication_failed	No key, the key is wrong or revoked, the member is suspended or the key’s organization is archived.
403	tariff_required	Webhooks are available from the “API.Max Growth” plan.
404	not_found	There is no object with this number or name, or you can’t see it.
429	rate_limited / throttled	Too often — more requests per second than your plan allows; how long to wait is in the Retry-After header.

Change a webhook

Any of the fields: address, channel list (replaces the previous one entirely), is_active. is_active=true enables a disabled webhook: errors are cleared and posts are sent from now on. A webhook disabled by datool.ru staff (disabled_reason=staff) cannot be enabled this way — 409 conflict, contact support.

Parameters

Name	Where	Description
id required number	path	Webhook number

Request body

JSON with the Content-Type: application/json header.

Field	Type	Description
url	string	New address
channels	list	A new channel list — replaces the previous one entirely
is_active	yes / no	true — enable again (errors are cleared), false — disable

Response fields

Field	Type	Description
id	number	Webhook number — in /v1/max/webhooks/{id}/ URLs and in events
url	string	The address events are sent to (https://)
is_active	yes / no	Whether the webhook is enabled
disabled_reason	string	Why it is disabled: failing — no successful delivery for a day, client — disabled by you, staff — by datool.ru staff; empty — enabled
channels	list	Numbers of the subscribed MAX channels
pending	number	Deliveries waiting to be sent
created_at	date and time	When the webhook was created (ISO 8601, Moscow time)
last_success_at	date and time or null	Last successful delivery
failing_since	date and time or null	Since when there have been no successful deliveries; null — all good
last_error	string	The last delivery error, briefly

Errors

Code	code	When
400	field errors	An invalid parameter or body field: the error comes under the field name, for example {"channels": ["Comma-separated channel numbers."]}.
401	not_authenticated / authentication_failed	No key, the key is wrong or revoked, the member is suspended or the key’s organization is archived.
403	tariff_required	Webhooks are available from the “API.Max Growth” plan.
403	read_only_key	The key has no “read and write” mark.
403	manager_required	A member’s key: webhooks can be changed by the owner or an administrator.
404	not_found	There is no object with this number or name, or you can’t see it.
409	conflict	The webhook was disabled by datool.ru staff — only support can enable it.
429	rate_limited / throttled	Too often — more requests per second than your plan allows; how long to wait is in the Retry-After header.
503	timeout	The database query took longer than 5 seconds — retry later or narrow the selection.

Delete a webhook

Delete a webhook together with its queue of undelivered events. Requires a “read and write” key. Response 204 without a body.

Parameters

Name	Where	Description
id required number	path	Webhook number

Errors

Code	code	When
401	not_authenticated / authentication_failed	No key, the key is wrong or revoked, the member is suspended or the key’s organization is archived.
403	tariff_required	Webhooks are available from the “API.Max Growth” plan.
403	read_only_key	The key has no “read and write” mark.
403	manager_required	A member’s key: webhooks can be changed by the owner or an administrator.
404	not_found	There is no object with this number or name, or you can’t see it.
429	rate_limited / throttled	Too often — more requests per second than your plan allows; how long to wait is in the Retry-After header.

Rotate the signing secret

A new signing secret: the previous one stops working immediately. The secret is in the response and is shown only once.

Parameters

Name	Where	Description
id required number	path	Webhook number

Response fields

Field	Type	Description
id	number	Webhook number — in /v1/max/webhooks/{id}/ URLs and in events
url	string	The address events are sent to (https://)
is_active	yes / no	Whether the webhook is enabled
disabled_reason	string	Why it is disabled: failing — no successful delivery for a day, client — disabled by you, staff — by datool.ru staff; empty — enabled
channels	list	Numbers of the subscribed MAX channels
pending	number	Deliveries waiting to be sent
created_at	date and time	When the webhook was created (ISO 8601, Moscow time)
last_success_at	date and time or null	Last successful delivery
failing_since	date and time or null	Since when there have been no successful deliveries; null — all good
last_error	string	The last delivery error, briefly
secret	string	The X-Datool-Signature signing secret. Shown only once — save it

Errors

Code	code	When
401	not_authenticated / authentication_failed	No key, the key is wrong or revoked, the member is suspended or the key’s organization is archived.
403	tariff_required	Webhooks are available from the “API.Max Growth” plan.
403	read_only_key	The key has no “read and write” mark.
403	manager_required	A member’s key: webhooks can be changed by the owner or an administrator.
404	not_found	There is no object with this number or name, or you can’t see it.
429	rate_limited / throttled	Too often — more requests per second than your plan allows; how long to wait is in the Retry-After header.

Test a webhook

A test delivery of a ping event without posts — to check the address and signature. One attempt, no retries; at most once a minute per webhook (more often — 429 throttled with a Retry-After header). The result appears in the last_success_at and last_error fields within a few seconds.

Parameters

Name	Where	Description
id required number	path	Webhook number

Response fields

Field	Type	Description
delivery	number	Delivery number (the X-Datool-Delivery header)
status	string	queued — added to the sending queue

Errors

Code	code	When
401	not_authenticated / authentication_failed	No key, the key is wrong or revoked, the member is suspended or the key’s organization is archived.
403	tariff_required	Webhooks are available from the “API.Max Growth” plan.
403	read_only_key	The key has no “read and write” mark.
403	manager_required	A member’s key: webhooks can be changed by the owner or an administrator.
404	not_found	There is no object with this number or name, or you can’t see it.
409	conflict	The webhook is disabled — enable it (is_active=true) and try again.
429	throttled	A webhook can be tested at most once a minute.
429	rate_limited / throttled	Too often — more requests per second than your plan allows; how long to wait is in the Retry-After header.