Ir para o conteúdo
NimbusNexus

Slack, Teams e Discord

O Slack, o Microsoft Teams e o Discord podem dar a um canal uma URL de webhook que posta nele tudo o que recebe — mas só no formato de mensagem de cada app, então eles recusam o envelope de evento que normalmente enviamos. Uma transformação resolve essa diferença. No final deste guia, você terá:

  • um endpoint apontado para a URL de webhook do seu canal;
  • o template desse app transformando cada evento em uma mensagem que ele aceita;
  • um evento de teste postado no canal.

Tempo total: cerca de 10 minutos.

Pré-requisitos

  • Um workspace do Webhooks em qualquer plano: os templates de chat são pipelines, que todos os planos incluem.
  • Permissão para adicionar um webhook ao canal: no Slack, para instalar um app no workspace; no Teams, para criar um workflow; no Discord, a permissão Manage Webhooks.
  • A verificação de endpoint desligada no projeto em que o endpoint vai ficar. Esses canais só aceitam mensagens no próprio formato, então nunca conseguem responder ao desafio de verificação, e um endpoint que precisa passar por ele não recebe nada. Os planos pagos permitem desligar a verificação; em um plano que a exige, esses canais não podem ser usados.

1 · Obter a URL de webhook do canal

Slack

Crie um app do Slack para o seu workspace e ative Incoming Webhooks nas configurações dele. Escolha Add New Webhook to Workspace, selecione o canal e autorize. Copie a URL, que se parece com https://hooks.slack.com/services/T…/B…/…. Os passos do próprio Slack estão em Enviar mensagens usando incoming webhooks.

Microsoft Teams

No Teams, abra Workflows e comece pelo template Send webhook alerts to a channel. Escolha a equipe e o canal, salve o workflow e copie a URL do webhook nos detalhes dele. Os passos da própria Microsoft estão em Criar webhooks de entrada com Workflows para o Microsoft Teams.

Discord

No Discord, abra Server Settings → Integrations → Webhooks e crie um webhook. Escolha o canal em que ele vai postar e depois Copy Webhook URL; a URL se parece com https://discord.com/api/webhooks/…/…. Os passos do próprio Discord estão em Introdução aos webhooks.

Trate a URL como um segredo: esses canais não verificam a nossa assinatura, então qualquer pessoa que a tenha pode postar no canal.

2 · Adicionar o endpoint

No console, escolha New endpoint na página Endpoints, cole a URL e inscreva o endpoint nos eventos que o canal deve ver. Mantenha a lista curta: um canal é lido por pessoas, e cada evento correspondente vira uma mensagem.

Pela API:

Shell
curl -sX POST https://webhooks.nimbusnexus.net/v1/endpoints \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.slack.com/services/T…/B…/…", "project_id": "prj_…",
       "subscriptions": [{"match_kind": "exact", "pattern": "invoice.paid"}]}'

3 · Começar pelo template

Abra o menu do endpoint na página Endpoints e escolha Transformation. Selecione Pipeline e, em Start from a template, o template do seu app — Use Slack message, Use Microsoft Teams card ou Use Discord message — e escolha Save. A partir de agora, cada entrega para este endpoint é enviada como uma mensagem:

TemplateO que o canal mostra
Slack messageO tipo do evento como título, o id e o horário dele e os dados em um bloco de código.
Microsoft Teams cardUm Adaptive Card com o tipo do evento, o id e o horário dele e os dados em fonte monoespaçada.
Discord messageUm embed com o tipo do evento como título, os dados em um bloco de código JSON e, embaixo, o id e o horário. Não menciona ninguém.

Cada template corta os dados para caber nos limites do app, e nada no evento consegue formatar a mensagem, mencionar alguém ou fechar o bloco de código antes da hora. Ao salvar, o pipeline passa a ser seu: ele não muda quando o template muda.

Pela API, GET /v1/transformations/templates retorna cada template com o seu pipeline: crie uma transformação com esse documento e depois aponte para ela o transformation_id do endpoint.

Um endpoint que já executa um dos presets antigos, que são scripts, continua executando-o sem mudanças.

4 · Testar

Em Test, na mesma página, escolha Run test. O teste executa o pipeline do editor com um evento recente das entregas do endpoint, ou com um que você colar, e mostra a mensagem que seria enviada. Nada é enviado.

Depois, envie um evento de verdade: Send test event, na página Overview do console, ou publique um evento em que o endpoint esteja inscrito:

Shell
curl -sX POST https://webhooks.nimbusnexus.net/v1/events \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "invoice.paid", "project_id": "prj_…", "payload": {"id": "in_123", "amount": 125000, "currency": "usd"}}'

A mensagem aparece no canal em poucos segundos. O Send test ping do endpoint não serve aqui: ele envia o ping fixo sem transformação, e o canal o recusa.

O que você fez

Agora, cada evento em que o endpoint está inscrito posta uma mensagem no seu canal. Abra uma entrega na página Deliveries para ver a mensagem que foi enviada; se o app respondeu com um erro, ele também aparece lá, nas tentativas da entrega.

Personalizar

As etapas do template agora são do seu pipeline, então você pode mudá-las como quaisquer outras. Para reservar o canal para os eventos de que as pessoas precisam, adicione uma etapa Filter com Send only matching events e duas condições, type is invoice.paid e data.amount is at least 100000, e leve-a para o topo, para que ela teste o evento antes de a mensagem ser montada. Em JSON:

JSON
{ "filter": { "type": "invoice.paid", "data": { "amount": { "$gte": 100000 } } } }

Uma entrega que o filtro descarta não é enviada e não conta como falha. Para mudar o que a mensagem diz, edite a etapa Reshape the body, que a monta; o console a mostra como JSON, então altere-a ali e escolha Apply. Os valores dela leem o evento por meio de caminhos e filtros, como {{ data.amount | money(data.currency) }}. Teste antes de salvar: uma execução que falha manda a entrega para a dead-letter queue e nunca envia o evento sem transformação.

Próximos passos