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"