Create template webhook

curl --request POST \
  --url https://api.hubmessage.io/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://destination/webhook",
  "description": "Template webhook",
  "events": [
    "UPDATE_TEMPLATE_STATUS",
    "UPDATE_TEMPLATE_CATEGORY"
  ],
  "signing": false,
  "authType": "NONE"
}
'

{
  "id": "8F2C00000000000000000000000000A1",
  "channelId": null,
  "instanceId": null,
  "url": "https://destination/webhook",
  "description": "Template webhook",
  "events": [
    "UPDATE_TEMPLATE_STATUS",
    "UPDATE_TEMPLATE_CATEGORY"
  ],
  "status": "ENABLED",
  "signing": false,
  "secret": null,
  "auth": {
    "type": "NONE",
    "configured": false
  },
  "payloadFormat": "DEFAULT",
  "customAttributes": {},
  "createdAt": "2026-07-15T19:00:00.000+00:00",
  "updatedAt": "2026-07-15T19:00:00.000+00:00"
}

POST

webhooks

curl --request POST \
  --url https://api.hubmessage.io/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://destination/webhook",
  "description": "Template webhook",
  "events": [
    "UPDATE_TEMPLATE_STATUS",
    "UPDATE_TEMPLATE_CATEGORY"
  ],
  "signing": false,
  "authType": "NONE"
}
'

{
  "id": "8F2C00000000000000000000000000A1",
  "channelId": null,
  "instanceId": null,
  "url": "https://destination/webhook",
  "description": "Template webhook",
  "events": [
    "UPDATE_TEMPLATE_STATUS",
    "UPDATE_TEMPLATE_CATEGORY"
  ],
  "status": "ENABLED",
  "signing": false,
  "secret": null,
  "auth": {
    "type": "NONE",
    "configured": false
  },
  "payloadFormat": "DEFAULT",
  "customAttributes": {},
  "createdAt": "2026-07-15T19:00:00.000+00:00",
  "updatedAt": "2026-07-15T19:00:00.000+00:00"
}

Overview

Creates a template webhook. It does not depend on an instance — the instanceId is stored as null automatically — and receives only WhatsApp template events. The events field accepts only UPDATE_TEMPLATE_STATUS and UPDATE_TEMPLATE_CATEGORY. Any non-template event results in 422.

`payloadFormat` is ignored

For template webhooks the format is always DEFAULT. You may omit the field; if sent (any value), it is silently discarded and persisted as DEFAULT.

HMAC signing

If signing: true, the secret field is generated and returned only in this response. Store it securely — it will not be shown again.

This endpoint requires the ENTERPRISE role on your account.

After creation, routing may take up to ~5 min to reflect (cache TTL).

Authorizations

Authorization

string

header

required

Secret Key generated in the Hub Message Security panel

Body

application/json

url

string

required

Destination URL for the events

Example:

"https://destination/webhook"

events

enum<string>[]

required

Template events only. At least one required. Any non-template event results in 422.

Minimum array length: 1

Accepted template events: UPDATE_TEMPLATE_STATUS (template status update — approved/rejected etc.) and UPDATE_TEMPLATE_CATEGORY (template category update).

Available options:

UPDATE_TEMPLATE_STATUS,

UPDATE_TEMPLATE_CATEGORY

Example:

[
  "UPDATE_TEMPLATE_STATUS",
  "UPDATE_TEMPLATE_CATEGORY"
]

description

string

Optional webhook description

Example:

"Template webhook"

signing

boolean

default:false

Enables HMAC-SHA256 signing. When true, generates and returns a 64-character hex secret only on create/update.

Example:

false

authType

enum<string>

default:NONE

Authentication type (flat form). Alternative to the auth object.

Available options:

NONE,

BEARER,

API_KEY,

BASIC,

CUSTOM_HEADER

Example:

"NONE"

token

string

Credential for BEARER (flat form)

key

string

Credential for API_KEY (flat form)

auth

object

Nested authentication form. For BASIC use username+password; for CUSTOM_HEADER use headerName+headerValue.

Show child attributes

payloadFormat

enum<string>

default:DEFAULT

Ignored for template webhooks — the format is always DEFAULT. May be omitted; if sent (any value), it is discarded and persisted as DEFAULT.

Available options:

DEFAULT

Example:

"DEFAULT"

customAttributes

object

Free-form map of extra attributes

Example:

{}

Response

Template webhook created successfully. channelId and instanceId come back null. The secret field is returned only in this response when signing is true.

string

Unique template webhook ID

Example:

"8F2C00000000000000000000000000A1"

channelId

string | null

Always null for template webhooks

Example:

null

instanceId

string | null

deprecated

Deprecated and always null for template webhooks

Example:

null

url

string

Destination URL for the events

Example:

"https://destination/webhook"

description

string | null

Webhook description

Example:

"Template webhook"

events

enum<string>[]

Configured template events

Accepted template events: UPDATE_TEMPLATE_STATUS (template status update — approved/rejected etc.) and UPDATE_TEMPLATE_CATEGORY (template category update).

Available options:

UPDATE_TEMPLATE_STATUS,

UPDATE_TEMPLATE_CATEGORY

Example:

[
  "UPDATE_TEMPLATE_STATUS",
  "UPDATE_TEMPLATE_CATEGORY"
]

status

enum<string>

Current webhook status

Available options:

ENABLED,

DISABLED

Example:

"ENABLED"

signing

boolean

Indicates whether HMAC signing is enabled

Example:

false

auth

object

Summary of the configured authentication — credentials are not returned for security reasons

Show child attributes

payloadFormat

enum<string>

Always DEFAULT for template webhooks

Available options:

DEFAULT

Example:

"DEFAULT"

customAttributes

object

Example:

{}

createdAt

string<date-time>

Example:

"2026-07-15T19:00:00.000+00:00"

updatedAt

string<date-time>

Example:

"2026-07-15T19:00:00.000+00:00"

secret

string | null

64-character hex HMAC secret — returned only when signing = true on create/update. null when signing is disabled. It cannot be retrieved afterwards.

Example:

null

Introduction

WhatsApp Official

Channels

Templates

Free messages

Webhooks

Create template webhook

Overview

`payloadFormat` is ignored

HMAC signing

Authorizations

Body

Response

Overview

payloadFormat is ignored

HMAC signing

Authorizations

Body

Response

`payloadFormat` is ignored