Atualizar projeto
Atualiza a configuração de webhook do projeto: o endereço, o token, os cabeçalhos personalizados, o segredo de assinatura e o envio de message.outgoing. Só os campos enviados mudam, e a resposta é o projeto atualizado. Escopo necessário: webhooks:write.
Parâmetros de caminho
idstring · uuidobrigatórioIdentificador do projeto (tenantId).
Corpo da requisição
namestringNome do projeto. Só da plataforma: enviado com uma chave de API, a requisição responde 403 e nada muda.
webhookBaseUrlstring · uriEndereço que recebe os eventos por POST. Conferido só quando muda: https, sem usuário e senha na URL, e o host precisa resolver só para endereços públicos; senão, 400. Redirecionamentos nunca são seguidos: uma resposta 3xx é uma entrega com falha.
webhookTokenstringVai no cabeçalho X-Webhook-Token de toda entrega. Só de escrita: nunca volta nas respostas.
webhookHeadersobject | nullCabeçalhos personalizados enviados em toda entrega, por nome ({"X-Crm-Account": "acme"}). Substitui os anteriores; null remove todos. Podem substituir Content-Type e X-Webhook-Token, mas nunca os cabeçalhos de assinatura. Só de escrita: as respostas trazem só os nomes, em webhookHeaderNames.
webhookSecretstring | nullSegredo de assinatura das entregas: com ele, toda entrega também traz X-Sales-Timestamp e X-Sales-Signature (sha256= seguido do HMAC-SHA256 de timestamp.corpo). null ou "" desliga a assinatura. Só de escrita: as respostas trazem só hasWebhookSecret.
emitOutgoingbooleanCom true, o projeto também recebe message.outgoing para cada mensagem 1:1 que o número envia: o eco de cada envio pela API e as mensagens digitadas no celular. Padrão do projeto: false.
maxPerMinutenumber | nullLimite próprio de envios por minuto de cada número do projeto, depois do aquecimento; null volta ao padrão do gateway. Só da plataforma: enviado com uma chave de API, a requisição responde 403 e nada muda.
maxPerHournumber | nullLimite próprio de envios por hora de cada número do projeto; null volta ao padrão do gateway. Só da plataforma: enviado com uma chave de API, a requisição responde 403 e nada muda.
maxPerDaynumber | nullLimite próprio de envios por dia de cada número do projeto; null volta ao padrão do gateway. Só da plataforma: enviado com uma chave de API, a requisição responde 403 e nada muda.
isActivebooleanAtiva ou desativa o projeto. Só da plataforma: enviado com uma chave de API, a requisição responde 403 e nada muda.
planIdstring | nullPlano da organização dona do projeto (a cobrança é da organização: todos os projetos dela mudam juntos); null remove o plano. Só da plataforma: enviado com uma chave de API, a requisição responde 403 e nada muda.
Respostas
| Código | Erro e descrição |
|---|---|
| 200 | O projeto atualizado, sem as credenciais do webhook. |
| 400 | O webhookBaseUrl foi recusado: precisa ser https, sem usuário e senha na URL, e o host precisa resolver só para endereços públicos. error diz qual regra falhou. |
| 400 | FST_ERR_VALIDATIONO corpo não segue o schema da operação (por exemplo, emitOutgoing que não é booleano), ou id não é um UUID; message diz o que está errado. |
| 401 | Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. A chave de um projeto desativado também responde 401. |
| 403 | A chave não tem o escopo webhooks:write; a mensagem de erro cita o escopo que falta. |
| 403 | O corpo traz um campo que só a plataforma muda (name, planId, isActive, maxPerMinute, maxPerHour ou maxPerDay); a mensagem lista quais. Nada muda. |
| 404 | O projeto não existe ou não é de quem chama (Tenant not found): uma chave de API alcança só o próprio projeto, e o de outra pessoa responde igual a um que não existe. |
| 409 | A requisição veio de uma aba antiga do painel, aberta no navegador, que sobrescreveria webhookToken e webhookHeaders: recarregue a página e tente de novo. Chamadas de servidor para servidor nunca recebem este 409. |
| 429 | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de Retry-After. Veja Limites.Cabeçalho: Retry-After |
Detalhes
name, planId, isActive e os limites maxPerMinute, maxPerHour e maxPerDay são só da plataforma: se algum deles vier com uma chave de API, a requisição inteira responde 403 e nada muda.
O token, os cabeçalhos e o segredo são só de escrita: nunca voltam nas respostas, que trazem hasWebhookSecret e webhookHeaderNames. As próximas entregas das conexões do projeto já usam os valores novos. Antes de trocar o endereço, teste-o com POST /tenants/webhook-test.
Guia: Projetos e conexões