# Subscribe to a webhook

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 URL to which notification messages are to be sent.
topic
required
string body Name of the topic about which the notification is to be sent. It must match the regular expression (opens new window) [0-9A-Za-z\.\-_]{8,128}.
expires
optional*
integer, DEFAULT=86400 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 86400 seconds (24 hours).

*

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=86400) is used.

# Response

Attribute Type Description
callback_url string URL to which notification messages are to be sent.
subscription dictionary
Details of the subscription.
Attribute Type Description
topic string Name of the topic about which the notification is to be sent.
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).

# 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 UUID of the confirmation message.
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 made (see confirm_a_webhook_subscription in order to confirm the subscription.
subscription dictionary
Details of the subscription.
Attribute Type Description
topic string Name of the topic about which the notification is to be sent.
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).

# Status codes

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