Skip to main content
POST
/
v1
/
channels
/
{channelId}
/
webhooks
curl --request POST \
  --url https://api.hubmessage.io/v1/channels/{channelId}/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://app.yourcompany.com/webhooks/hubmessage",
  "events": [
    "MESSAGE_RECEIVED"
  ]
}
'
{
  "id": "A1B2C3D4E5F6789012345678901234AB",
  "instanceId": "019E4C54B1B375A28970B605CA9B03C3",
  "url": "https://app.yourcompany.com/webhooks/hubmessage",
  "description": null,
  "events": [
    "MESSAGE_RECEIVED",
    "MESSAGE_STATUS"
  ],
  "status": "ENABLED",
  "signing": true,
  "secret": "a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab",
  "auth": {
    "type": "NONE",
    "configured": false
  },
  "payloadFormat": "DEFAULT",
  "customAttributes": {},
  "createdAt": "2025-01-15T10:30:00.000+0000",
  "updatedAt": "2025-01-15T10:30:00.000+0000"
}

​
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:
["MESSAGE_RECEIVED", "MESSAGE_STATUS"]
​
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. Z_API maintains compatibility with systems integrated via Z-API.

Available options:
DEFAULT,
Z_API
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"

​
instanceId
string

ID of the channel this webhook belongs to

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:
["MESSAGE_RECEIVED", "MESSAGE_STATUS"]
​
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,
Z_API
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"