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 contém as credenciais do webhook. Não é necessário nenhum cabeçalho de autenticação adicional. Mantenha o URL completo em segredo.

Pedido mínimo

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

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.
• 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.