Pular para o conteúdo principal
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.suaempresa.com/webhooks/hubmessage",
  "events": [
    "MESSAGE_RECEIVED"
  ]
}
'
{
  "id": "A1B2C3D4E5F6789012345678901234AB",
  "instanceId": "019E4C54B1B375A28970B605CA9B03C3",
  "url": "https://app.suaempresa.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"
}

​
Conceituação

Registra um novo endpoint de webhook no canal. A partir da criação, o passa a enviar os eventos configurados para a URL informada. Um canal pode ter múltiplos webhooks — útil para enviar eventos diferentes para sistemas diferentes, ou para manter webhooks com formatos distintos.

​
Assinatura HMAC

Se signing: true, o campo secret é gerado automaticamente e retornado apenas nesta resposta. Armazene-o com segurança — ele não será exibido novamente em nenhuma outra chamada. Use o secret para verificar a autenticidade das requisições recebidas no seu servidor. Calcule o HMAC-SHA256 sobre o body recebido usando o secret e compare com o header de assinatura enviado pelo .
Este endpoint requer a role ENTERPRISE na sua conta.
O channelId é obtido através do endpoint Criar canal.

Autorizações

​
Authorization
string
header
obrigatório

Secret Key gerada no painel de Segurança do Hub Message

Parâmetros de caminho

​
channelId
string
obrigatório

ID do canal

Exemplo:

"019E4C54B1B375A28970B605CA9B03C3"

Corpo

application/json
​
url
string
obrigatório

URL de destino dos eventos (máx. 2048 caracteres)

Exemplo:

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

​
events
enum<string>[]
obrigatório

Tipos de evento a receber. Pelo menos um obrigatório.

Opções disponíveis:
MESSAGE_RECEIVED,
MESSAGE_DELIVERY,
MESSAGE_STATUS,
RECEIVED_STATUS,
RECEIVED_AND_DELIVERY,
CONNECTED,
DISCONNECTED,
PRESENCE_CHAT,
INITIAL_DATA,
BLOCK
Exemplo:
["MESSAGE_RECEIVED", "MESSAGE_STATUS"]
​
description
string

Descrição opcional do webhook

Exemplo:

"Webhook principal de produção"

​
signing
boolean
padrão:false

Habilita assinatura HMAC-SHA256. Quando true, um secret de 64 caracteres hex é gerado e retornado apenas na criação/atualização. Use-o para verificar a autenticidade das requisições recebidas.

Exemplo:

true

​
auth
object

Configura como o Hub Message se autentica ao chamar sua URL

​
payloadFormat
enum<string>
padrão:DEFAULT

Formato do payload entregue ao webhook. Z_API mantém compatibilidade com sistemas integrados via Z-API.

Opções disponíveis:
DEFAULT,
Z_API
Exemplo:

"DEFAULT"

​
customAttributes
object

Atributos extras

Exemplo:
{}

Resposta

Webhook criado com sucesso. O campo secret é retornado apenas nesta resposta quando signing é true — armazene-o com segurança.

​
id
string

ID único do webhook

Exemplo:

"A1B2C3D4E5F6789012345678901234AB"

​
instanceId
string

ID do canal ao qual o webhook pertence

Exemplo:

"019E4C54B1B375A28970B605CA9B03C3"

​
url
string

URL de destino dos eventos

Exemplo:

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

​
description
string | null

Descrição do webhook

Exemplo:

"Webhook principal de produção"

​
events
string[]

Tipos de evento configurados

Exemplo:
["MESSAGE_RECEIVED", "MESSAGE_STATUS"]
​
status
enum<string>

Status atual do webhook

Opções disponíveis:
ENABLED,
DISABLED
Exemplo:

"ENABLED"

​
signing
boolean

Indica se a assinatura HMAC está habilitada

Exemplo:

true

​
auth
object

Resumo da autenticação configurada — credenciais não são retornadas por segurança

​
payloadFormat
enum<string>

Formato do payload entregue

Opções disponíveis:
DEFAULT,
Z_API
Exemplo:

"DEFAULT"

​
customAttributes
object

Atributos extras configurados

Exemplo:
{}
​
createdAt
string<date-time>

Data de criação

Exemplo:

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

​
updatedAt
string<date-time>

Data da última atualização

Exemplo:

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

​
secret
string

Segredo HMAC de 64 caracteres hex — retornado apenas quando signing é habilitado no create ou update. Armazene-o com segurança; não poderá ser recuperado depois.

Exemplo:

"a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab"