Webhooks de saída

Módulo

Configure para onde o Connect envia os eventos da sua conexão. Entrega com assinatura HMAC (x-zyron-signature), retry com backoff e dead-letter; eventos estruturados whatsapp.message.received|sent|delivered|read|failed e whatsapp.connection.updated.

GETConsultar webhook/webhooks PUTConfigurar webhook/webhooks DELETERemover webhook/webhooks GETEntregas do webhook/webhooks/deliveries

GET/webhooksEscopo: readOficial + Básico

Lista as configurações de webhook.

Uma configuração por conexão. O secret é retornado ao dono da chave — é ele que valida a assinatura x-zyron-signature na ponta. structured_events lista o catálogo de eventos v2.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`opcional	uuid	Filtra por conexão.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/webhooks?connection_id=<CONNECTION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Configurações retornadas.

Exemplo de resposta

{
  "data": [
    {
      "id": "5f0d5a44-1187-4f1e-a2b0-1d40c07b0e10",
      "connection_id": "<CONNECTION_ID>",
      "url": "https://seu-n8n.com/webhook/zyron",
      "events": ["whatsapp.message.received", "whatsapp.message.failed"],
      "secret": "zwh_9f2c...",
      "active": true
    }
  ],
  "structured_events": [
    "whatsapp.message.received",
    "whatsapp.message.sent",
    "whatsapp.message.delivered",
    "whatsapp.message.read",
    "whatsapp.message.failed",
    "whatsapp.connection.updated"
  ]
}

PUT/webhooksEscopo: writeOficial + Básico

Cria ou atualiza o webhook de uma conexão.

events vazio assina todos os eventos. Aceita os eventos estruturados v2 e os nomes nativos do provider (compatibilidade). Sem secret no corpo, o Connect mantém o atual ou gera um novo zwh_.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`connection_id`obrigatório	uuid	Conexão dona do webhook.
`url`obrigatório	URL	Endpoint http(s) que recebe os eventos.
`events`opcional	string[]	Eventos assinados. Vazio = todos.
`secret`opcional	string	Segredo do HMAC. Opcional; gerado quando ausente.
`active`opcional	boolean	Padrão true. false pausa as entregas.

Exemplos prontos

curl -X PUT "https://connect.zyronstack.com/api/v1/webhooks" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "connection_id": "<CONNECTION_ID>",
  "url": "https://seu-n8n.com/webhook/zyron",
  "events": ["whatsapp.message.received", "whatsapp.message.failed"]
}'

Respostas

201	Webhook criado.
200	Webhook atualizado.
422	URL inválida ou evento não suportado pela conexão.

DELETE/webhooksEscopo: writeOficial + Básico

Desativa o webhook de uma conexão.

Pausa as entregas mantendo configuração e histórico para auditoria. Reative com PUT { active: true }.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`obrigatório	uuid	Conexão do webhook.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X DELETE "https://connect.zyronstack.com/api/v1/webhooks?connection_id=<CONNECTION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Webhook desativado.
404	Nenhum webhook configurado.

GET/webhooks/deliveriesEscopo: readOficial + Básico

Histórico de entregas do webhook.

Cada entrega mostra evento, status (pending, delivered, failed, dead), tentativas, último HTTP status e erro. Use para depurar a sua ponta sem abrir o painel.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`opcional	uuid	Filtra por conexão.
`status`opcional	pending \| delivered \| failed \| dead	Filtra pelo estado da entrega.
`event`opcional	string	Filtra pelo nome do evento entregue.
`limit`opcional	number	Quantidade de registros por página. Padrão 50; máximo 200 na maioria das listas.
`offset`opcional	number	Índice inicial da página. Use pagination.next_offset para buscar a próxima página.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/webhooks/deliveries?connection_id=<CONNECTION_ID>&status=failed" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Entregas retornadas.

Exemplo de resposta

{
  "data": [
    {
      "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "connection_id": "<CONNECTION_ID>",
      "event": "whatsapp.message.received",
      "status": "delivered",
      "attempts": 1,
      "last_status": 200,
      "last_error": null,
      "target_url": "https://seu-n8n.com/webhook/zyron",
      "delivered_at": "2026-07-14T13:28:29.120Z",
      "created_at": "2026-07-14T13:28:27.898Z"
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 1, "next_offset": null }
}