Webhooks de entrada

Os webhooks de entrada permitem que ferramentas externas publiquem mensagens automáticas num canal do HansaChat. Utilize-os para atualizações de implementação, alertas de monitorização, notificações de tickets, envios de formulários e outros eventos que devam aparecer na conversa de equipa.

Apenas os administradores do workspace podem criar e gerir webhooks de entrada.

Criar um webhook

1. Abra as Definições na barra lateral, no canto inferior esquerdo.
2. Selecione Webhooks.
3. Escolha Criar webhook.
4. Introduza um nome de webhook claro, como CI Deployments.
5. Escolha o canal onde as mensagens devem ser publicadas.
6. Opcionalmente, introduza um URL de ícone.
7. Escolha Criar webhook.

Copiar o URL do webhook

Depois da criação, o HansaChat mostra o URL do webhook uma única vez. Copie-o e guarde-o em segurança na ferramenta externa que vai enviar os eventos.

Se fechar este ecrã sem guardar o URL, rode o URL para gerar um novo segredo. O URL anterior deixa de funcionar imediatamente após a rotação.

Gerir webhooks

Na página de Webhooks, os administradores podem:

• Editar o nome do webhook, o canal, o URL do ícone ou o estado ativo.
• Desativar um webhook para rejeitar novas mensagens sem o eliminar.
• Rodar URL para invalidar o segredo antigo e gerar um novo URL.
• Eliminar um webhook. As mensagens existentes na conversa não são removidas.

Referência técnica

Envie um pedido POST para o URL do webhook:

https://{workspace-domain}/api/webhooks/{publicID}/{secret}

O URL identifica o webhook. Cada entrega tem também de ser assinada com o segredo do webhook: envie um cabeçalho X-Webhook-Signature com um timestamp e uma assinatura HMAC-SHA256 calculada sobre o corpo do pedido. Entregas não assinadas ou expiradas são rejeitadas com 401. Mantenha o URL completo em segredo.

Assine as suas entregas

Cada pedido precisa de um cabeçalho X-Webhook-Signature neste formato:

t=<unix timestamp>,v1=<hex signature>

A assinatura é um digest HMAC-SHA256 sobre <timestamp>.<corpo> — o timestamp Unix, um ponto e o corpo não processado do pedido — utilizando como chave o segredo do webhook do URL. Entregas com um timestamp com mais de 5 minutos são rejeitadas, por isso assine cada entrega imediatamente antes de a enviar.

Bash (openssl):

URL='https://{workspace-domain}/api/webhooks/{publicID}/{secret}'
BODY='{"text":"Deployment completed successfully"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | \
  openssl dgst -sha256 -hmac "$(basename "$URL")" | awk '{print $NF}')
curl -X POST "$URL" \
  -H 'Content-Type: application/json' \
  -H "X-Webhook-Signature: t=$TS,v1=$SIG" \
  -d "$BODY"

Python:

import hashlib, hmac, time, requests

url = "https://{workspace-domain}/api/webhooks/{publicID}/{secret}"
secret = url.rsplit("/", 1)[-1]
body = b'{"text":"Deployment completed successfully"}'
ts = str(int(time.time()))
sig = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
requests.post(url, data=body,
              headers={"Content-Type": "application/json",
                       "X-Webhook-Signature": f"t={ts},v1={sig}"})

Node.js:

import { createHmac } from "node:crypto";

const url = "https://{workspace-domain}/api/webhooks/{publicID}/{secret}";
const secret = new URL(url).pathname.split("/").at(-1);
const body = JSON.stringify({ text: "Deployment completed successfully" });
const ts = Math.floor(Date.now() / 1000);
const sig = createHmac("sha256", secret).update(`${ts}.${body}`).digest("hex");
await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Webhook-Signature": `t=${ts},v1=${sig}`,
  },
  body,
});

Depois de o HansaChat devolver ok, a mensagem aparece no canal selecionado.

Payload compatível com o Slack

O endpoint aceita payloads JSON compatíveis com o Slack, com text, blocks e attachments.

{
  "text": "Deployment completed successfully",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "Deployment completed"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Branch `main` is now live."
      }
    }
  ]
}

Pelo menos um de text, blocks ou attachments tem de conter texto legível.

Campos suportados

O tamanho máximo do payload é 1 MB.

Limites de pedidos

A ingestão de webhooks de entrada tem um limite de pedidos por URL de webhook.

Cada webhook pode aceitar até 10 pedidos autenticados por minuto e até 100 pedidos autenticados por hora. Quando qualquer um destes limites é atingido, o HansaChat devolve 429 resource_exhausted.

Contacte-nos se quiser aumentar o limite de pedidos.

Os limites do payload são aplicados separadamente: o tamanho máximo do corpo é 1 MB, blocks aceita até 50 itens, attachments aceita até 100 itens e o payload tem de conter texto legível.

Idempotência

Acrescente um cabeçalho Idempotency-Key quando o seu sistema possa repetir o mesmo evento:

curl -X POST 'https://{workspace-domain}/api/webhooks/{publicID}/{secret}' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: deploy-1247' \
  -d '{"text":"Deployment #1247 completed"}'

Se o HansaChat receber novamente a mesma chave de idempotência para o mesmo webhook, devolve 200 ok sem criar uma mensagem duplicada.

Respostas

Os pedidos bem-sucedidos devolvem:

ok

Erros comuns:

Dicas de segurança

• Trate os URLs de webhook como palavras-passe.
• Guarde os URLs no gestor de segredos da sua ferramenta externa.
• Assine cada entrega com o segredo do webhook — os pedidos não assinados são rejeitados.
• Rode o URL se este tiver sido exposto ou perdido.
• Desative os webhooks que não utiliza.
• Utilize um webhook dedicado por sistema externo, para que o acesso possa ser revogado de forma limpa.