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:
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:
| Template | O que o canal mostra |
|---|---|
| Slack message | O tipo do evento como título, o id e o horário dele e os dados em um bloco de código. |
| Microsoft Teams card | Um Adaptive Card com o tipo do evento, o id e o horário dele e os dados em fonte monoespaçada. |
| Discord message | Um 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:
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:
{ "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
- Transformações — templates, etapas de um pipeline, testes e o que acontece quando uma execução falha.
- Verificação de endpoint — receptores que não conseguem responder ao desafio.
- Entregas e retentativas — estados, retentativas e como reenviar.