Skip to main content
POST

​
Overview

Registers a new webhook endpoint on the channel. From creation onwards, starts sending the configured events to the provided URL. A channel can have multiple webhooks — useful for sending different events to different systems, or for maintaining webhooks with different formats.

​
HMAC signing

If signing: true, a secret is automatically generated and returned only in this response. Store it securely — it will not be shown again in any other call. Use the secret to verify the authenticity of requests received on your server. Compute HMAC-SHA256 over the received body using the secret and compare it with the signing header sent by .
This endpoint requires the ENTERPRISE role on your account.
The channelId is obtained from the Create channel endpoint.

Authorizations

​
Authorization
string
header
required

Secret Key generated in the Hub Message Security panel

Path Parameters

​
channelId
string
required

Channel ID

Example:

"019E4C54B1B375A28970B605CA9B03C3"

Body

application/json
​
url
string
required

Event destination URL (max. 2048 characters)

Example:

"https://app.yourcompany.com/webhooks/hubmessage"

​
events
enum<string>[]
required

Event types to receive. At least one required.

Available options:
MESSAGE_RECEIVED,
MESSAGE_DELIVERY,
MESSAGE_STATUS,
RECEIVED_STATUS,
RECEIVED_AND_DELIVERY,
CONNECTED,
DISCONNECTED,
PRESENCE_CHAT,
INITIAL_DATA,
BLOCK
Example:
​
description
string

Optional webhook description

Example:

"Main production webhook"

​
signing
boolean
default:false

Enables HMAC-SHA256 signing. When true, a 64-character hex secret is generated and returned only on create/update. Use it to verify the authenticity of incoming requests.

Example:

true

​
auth
object

Configures how Hub Message authenticates when calling your URL

​
payloadFormat
enum<string>
default:DEFAULT

Payload format delivered to the webhook.

Available options:
DEFAULT
Example:

"DEFAULT"

​
customAttributes
object

Extra attributes

Example:

Response

Webhook created successfully. The secret field is returned only in this response when signing is true — store it securely.

​
id
string

Unique webhook ID

Example:

"A1B2C3D4E5F6789012345678901234AB"

​
channelId
string

ID of the channel this webhook belongs to

Example:

"019E4C54B1B375A28970B605CA9B03C3"

​
instanceId
string
deprecated

Deprecated — use channelId instead

Example:

"019E4C54B1B375A28970B605CA9B03C3"

​
url
string

Event destination URL

Example:

"https://app.yourcompany.com/webhooks/hubmessage"

​
description
string | null

Webhook description

Example:

"Main production webhook"

​
events
string[]

Configured event types

Example:
​
status
enum<string>

Current webhook status

Available options:
ENABLED,
DISABLED
Example:

"ENABLED"

​
signing
boolean

Indicates whether HMAC signing is enabled

Example:

true

​
auth
object

Summary of configured authentication — credentials are not returned for security

​
payloadFormat
enum<string>

Delivered payload format

Available options:
DEFAULT
Example:

"DEFAULT"

​
customAttributes
object

Configured extra attributes

Example:
​
createdAt
string<date-time>

Creation date

Example:

"2025-01-15T10:30:00.000+0000"

​
updatedAt
string<date-time>

Last update date

Example:

"2025-01-15T10:30:00.000+0000"

​
secret
string

64-character hex HMAC secret — returned only when signing is enabled on create or update. Store it securely; it cannot be retrieved later.

Example:

"a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab"