Webhooks

Um webhook é uma URL ligada a um canal. Quando ela recebe um POST com um JSON, a mensagem aparece no canal, como se fosse de um "bot" que só sabe enviar. Não precisa de token, conta nem conexão, só do endereço. É o jeito mais rápido de mandar alertas, resultados de CI e avisos de scripts.

Ele envia e cuida das mensagens que ele mesmo enviou (listar, ler, editar e apagar). Para ler o resto do canal, reagir ou receber o que acontece no servidor, use um bot.

Criar um webhook

1. No SquadCall, abra o menu do servidor e vá em Integrações (só o dono e os administradores veem).
2. Abra Webhooks e crie um: escolha o canal e dê um nome.
3. Copie a URL. Ela aparece uma vez só; se perder, gere outra.

A URL tem este formato:

https://squadcall.gg/chat-api/v1/webhooks/ID/TOKEN

Enviar uma mensagem

curl -X POST "https://squadcall.gg/chat-api/v1/webhooks/ID/TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "Monitor",
    "content": "API **lenta** em produção",
    "embeds": [{ "title": "p95 = 2,4 s", "color": 15548997, "fields": [{ "name": "Região", "value": "sa-east-1", "inline": true }] }]
  }'

Markdown, embeds e botões estão em Formatação. O JSON é o mesmo dos webhooks do Discord: troque a URL do Discord pela do SquadCall e pronto.

Acentos no Windows

O corpo precisa ir em UTF-8. No CMD e no PowerShell, um curl -d '...' com acentos pode sair numa codificação do Windows e chegar como "voc� est�". Guarde o JSON num arquivo salvo em UTF-8 e envie o arquivo:

curl -X POST "https://squadcall.gg/chat-api/v1/webhooks/ID/TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data-binary @mensagem.json

Pela lib, em Node, isso já vem certo.

Ver, editar e apagar as próprias mensagens

A mesma URL serve para as mensagens que o webhook enviou. Use o id que vem na resposta de ?wait=true. As rotas só enxergam as mensagens da própria integração no canal do webhook; qualquer outra dá 404.

# editar
curl -X PATCH "https://squadcall.gg/chat-api/v1/webhooks/ID/TOKEN/messages/MENSAGEM" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data-binary @nova.json

# apagar
curl -X DELETE "https://squadcall.gg/chat-api/v1/webhooks/ID/TOKEN/messages/MENSAGEM"

Uma mensagem editada mostra "editada", como no resto do chat. Apagar remove também os anexos e avisa quem escuta eventos. Ainda não há métodos para isso na lib: use a API direto.

Pela lib

import { WebhookClient, EmbedBuilder } from 'nonseqchat-bot';

const hook = new WebhookClient(process.env.NONSEQ_WEBHOOK_URL);
await hook.send({ content: 'Backup concluído', embeds: [new EmbedBuilder().setTitle('12,4 GB').setColor('blue')] });
await hook.send({ content: 'Primeira mensagem do tópico', threadName: 'Backups de outubro' });

Instale com npm install nonseqchat-bot (Node 18 ou mais novo). Um exemplo completo, webhook.mjs, está na pasta examples/ da lib.

Limites e erros

• 30 mensagens por minuto em cada URL.
• 204 sem corpo quando der certo; com ?wait=true, 200 com a mensagem criada.
• Os erros vêm como { "message": "..." } em português, com o status HTTP. 404: a URL não existe ou foi trocada. 429: rápido demais.

Segurança

• Quem tem a URL publica no canal, então trate como senha: variável de ambiente, nunca no código nem no git.
• Se vazar, gere outra em Integrações > Webhooks; a antiga para na hora.
• Apagar a integração invalida a URL. As mensagens já enviadas continuam.