Webhook subscribe

This endpoint creates a webhook subscription for a given topic.

Method	Path	Operation*
POST	/notifications/webhooks	webhook_subscribe

*

In order for a user to perform the "webhook_subscribe" operation, the "webhook_subscribe" permission must be included in the list of allowed actions in the statement of the user's role.

Request

Parameter	Type	In	Description
callback_url required	string	body	Target URL to which messages are to be delivered. It can have maximum 512 characters.
topic required	string	body	Name of the subscription topic. It must match the regular expression(opens new window) ^[0-9A-Za-z\-]{3,48}$.
client_secret optional*	string	body	Client secret provided for the purpose of calculating a notification hash to be used for hash verification. It must be a URL-safe-Base64 compatible 16 character long string.
expires optional**	integer, DEFAULT=604800	body	Time in seconds when the notification subscription expires counted from the time of the creation of the subscription. The maximum and default value is 604800 seconds (7 days).

*

The "client_secret" parameter is optional and does not need to be included in the request body when refreshing subscriptions. If it is not included in the request body, the hash is not calculated and a server_secret is not be returned.

**

The "expires" parameter is optional and does not need to be included in the request body when creating subscriptions. If it is not included in the request body, its default value (DEFAULT=604800) is used.

Response

Attribute	Type	Description
callback_url	string	Target URL to which messages are to be delivered. It can have maximum 512 characters.
subscription	dictionary	Subscription details. Attribute Type Description topic string Name of the subscription topic. It must match the regular expression(opens new window) ^[0-9A-Za-z\-]{3,48}$. account string Account UUID. validity_ts timestamp Time at which the subscription expires. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).
server_secret	string	URL-safe-Base64 compatible 16-character long string to be used in the hash verification process. It must match the RegEx ^[A-Za-z0-9\-_=]$.

Confirmation message

The call to the endpoint returns a confirmation message to the provided callback URL.

Attribute	Type	Description
type	string	Message type. For messages generating a "confirmation_url" value should be "Confirmation".
message	string	Message UUID.
sent_ts	timestamp	Time at which the message was sent. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).
confirmation_url	string	URL to which a GET request needs to be sent (see confirm_a_webhook_subscription in order to confirm the subscription.
subscription	dictionary	Subscription details. Attribute Type Description topic string Name of the subscription topic. It must match the regular expression(opens new window) ^[0-9A-Za-z\-]{3,48}$. account string Account UUID. validity_ts timestamp Time at which the subscription expires. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).
hash	string	Message hash. Please see the Hash verification section for more details.

Status codes

Requests to this endpoint result in generic status codes. For a comprehensive list of status codes, please consult the Status codes section.