Synergy Connect

Documentação

Alterar um webhook

PATCH/v1/webhooks/{hook_id}

Muda só o que vier no corpo. Toda alteração recomeça a saúde do webhook em cada número: é assim que enabled: true reativa um webhook suspenso.

Uma URL nova, um modo de verificação novo ou — na verificação ping — headers novos provam a URL de novo antes de valer. headers mescla com os atuais: um nome com valor grava, um nome com null remove.

Com a conta em modo leitura ou suspensa só é aceito desativar ({ "enabled": false }, sozinho).

Requer#

Escopo da chave
Gerenciar webhooks managementComo os escopos funcionam
Recurso do plano
API e webhooks apiVer os planos que incluem
Formato
Próprio do Synergy. Erros em { "error": "…" }.

Parâmetros#

No caminho#

No caminho
NomeTipoObrigatórioDescrição
hook_idstringobrigatórioO id do webhook.

Cabeçalhos#

Cabeçalhos
NomeTipoObrigatórioDescrição
AuthorizationstringobrigatórioSua chave de API, no formato Bearer <chave>. Veja Autenticação.

Corpo#

Tipo de conteúdo: application/json.

Campos do corpo
NomeTipoObrigatórioDescrição
urlstringopcionalURL nova: é provada de novo antes de valer.
verifyTokenstringopcionalO token que a URL confere no handshake da Meta (hub.verify_token). Obrigatório com verification: "meta". Não é guardado. Mande junto quando a alteração refaz a verificação meta.
verificationstringopcionalping (padrão): a URL responde 2xx a um POST assinado de teste (synergy_ping). meta: a URL responde ao GET hub.challenge da Meta, e verifyToken é obrigatório. Valores: ping, meta.
headersobjectopcionalMescla com os headers atuais: um nome com valor grava, um nome com null remove. Headers próprios enviados em toda entrega (por exemplo Authorization): até 10, nomes só com letras, dígitos e hífen (1 a 64 caracteres), sem repetir e fora dos reservados (host, content-length, content-type, transfer-encoding, connection, keep-alive, upgrade, te, trailer, proxy-authorization, proxy-connection, user-agent, x-hub-signature-256, x-hub-signature, x-synergy-*). Os valores nunca voltam em nenhuma resposta: só os nomes, em headerNames.
fieldsstring[]opcionalOs eventos que o webhook recebe: os nomes da Meta, mais statuses (que a Meta entrega dentro de messages e aqui é uma escolha à parte) e synergy_conversations. Veja webhooks neste documento.
statusesstring[] | nullopcionalFiltro dentro de statuses: só estes status chegam. null = todos.
instanceIdsstring[] | nullopcionalOs números que o webhook cobre, pelo id do número na Synergy (64 hex; o mesmo de X-Synergy-Instance-Id). null = todos os números da organização, inclusive os conectados depois. Uma chave limitada a alguns números precisa listar números dela.
enabledbooleanopcionalfalse desativa o webhook (e descarta a fila dele); true reativa e recomeça limpo em todos os números.
namestring | nullopcional

Respostas#

Respostas
StatusCódigoQuando acontece
200—Webhook alterado
400—O corpo não passa na validação (issues traz os problemas, no formato do zod)
400—A URL nova não respondeu à verificação
400—Chave limitada a alguns números
400—Headers demais depois da mescla
401—Chave revogada ou desconhecida
401190Chave malformada ou forjada
403—A chave não tem o escopo management
403—O plano da organização não inclui a API
403—A conta está em modo leitura ou suspensa por falta de pagamento
404—Webhook não encontrado
413—Corpo grande demais
429—Limite de taxa

Os erros no formato da Meta trazem o código em error.code. Ver todos os erros.

Corpo da resposta 200#

Campos da resposta 200
NomeTipoObrigatórioDescrição
rowobjectobrigatório
row.idstringobrigatório
row.urlstringobrigatório
row.fieldsstring[]obrigatório
row.statusesstring[] | nullobrigatório
row.instanceIdsstring[] | nullobrigatório
row.enabledbooleanobrigatório
row.verificationstringobrigatórioValores: meta, ping.
row.headerNamesstring[] | nullobrigatórioOs NOMES dos headers próprios; os valores nunca voltam.
row.disabledReasonstring | nullobrigatório
row.createdBystringobrigatórioO id do usuário que criou, ou key:<id da chave> quando foi pela API.
row.createdAtintegerobrigatórioQuando foi criado (ms desde 1970).
row.updatedAtintegerobrigatórioA versão do webhook: toda alteração muda, e recomeça a saúde dele em cada número (ms desde 1970).
row.namestring | nullobrigatórioUm rótulo seu (o node do n8n usa n8n · <workflow> · prod|test). Opcional.
pendingintegerobrigatórioQuantos números ainda não receberam esta alteração. A Synergy repete o envio sozinha; 0 = já vale em todos.

Limites de taxa#

  • Gestão: 30 requisições a cada 60 s por chave (API_MGMT_LIMIT).

Notas#

  • Refazer a verificação meta (URL nova, ou troca de ping para meta) exige verifyToken no mesmo PATCH: ele não é guardado.
  • A fila de eventos pendentes não é apagada por uma alteração: sai com a configuração nova (URL, segredo, headers).
Requisição

curl

curl -X PATCH 'https://api.synergyconnect.com.br/v1/webhooks/7c1f0c7e-4b53-4c7b-9a51-3f6f0a2d9e10' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"fields":["messages","statuses","synergy_conversations"]}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v1/webhooks/7c1f0c7e-4b53-4c7b-9a51-3f6f0a2d9e10', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "fields": [
      "messages",
      "statuses",
      "synergy_conversations"
    ]
  }),
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.patch(
    "https://api.synergyconnect.com.br/v1/webhooks/7c1f0c7e-4b53-4c7b-9a51-3f6f0a2d9e10",
    headers={
        "Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}",
    },
    json={
        "fields": [
            "messages",
            "statuses",
            "synergy_conversations",
        ],
    },
)
print(res.status_code, res.json())
Resposta

200

{
  "row": {
    "id": "7c1f0c7e-4b53-4c7b-9a51-3f6f0a2d9e10",
    "url": "https://hooks.example.com/synergy",
    "fields": [
      "messages",
      "statuses",
      "synergy_conversations"
    ],
    "statuses": null,
    "instanceIds": null,
    "enabled": true,
    "verification": "ping",
    "headerNames": [
      "Authorization"
    ],
    "disabledReason": null,
    "createdBy": "key:0b9c4d1e-52a7-4f6b-8c3d-1e2f3a4b5c6d",
    "createdAt": 1767225600000,
    "updatedAt": 1767229200000,
    "name": null
  },
  "pending": 0
}

400

{
  "error": "Invalid body",
  "issues": [
    {
      "code": "invalid_type",
      "expected": "array",
      "path": [
        "fields"
      ],
      "message": "Invalid input: expected array, received undefined"
    }
  ]
}

Há 4 casos com este status; veja a tabela de respostas.

401

{
  "error": "Invalid or revoked key"
}

Há 2 casos com este status; veja a tabela de respostas.

403

{
  "error": "This key lacks the management scope"
}

Há 3 casos com este status; veja a tabela de respostas.

404

{
  "error": "Webhook not found"
}

413

{
  "error": "The body is too large (16 KB max)"
}

429

{
  "error": "Rate limit hit"
}

Ficou com dúvida? Escreva para suporte@synergyconnect.com.br.