Envie a primeira mensagem do seu sistema para o Joii.

Crie uma conexão para o canal de destino

Abra Configurações → Integrações → Aplicativos e alertas, escolha Webhook e informe um nome para identificar a origem. Selecione um canal interno em que você possa publicar. Para configurar a conexão, sua conta também precisa ter permissão para gerenciar integrações; em canal público, entre nele antes.

Escolha URL secreta para o primeiro teste. Copie a URL exibida ao criar a conexão e guarde-a como segredo no sistema que vai enviar os eventos. Ela é uma credencial de publicação e não deve entrar em código público, capturas de tela ou mensagens abertas. Para outro canal, crie outra conexão.

O modo Assinatura Standard Webhooks exige assinatura em toda requisição e usa os cabeçalhos webhook-id, webhook-timestamp e webhook-signature. O exemplo abaixo usa o modo URL secreta; não funciona sozinho numa conexão configurada para assinatura.

Envie título, texto e um link opcional

Faça um POST na URL gerada pelo Joii com Content-Type: application/json. O corpo aceita title, text e url. Basta título ou texto; o link, quando enviado, precisa usar HTTPS.

{
  "title": "Backup concluído",
  "text": "Execução backup-2026-09-22-001 concluída. Confira o relatório.",
  "url": "https://painel.example.com/backups/backup-2026-09-22-001"
}

Este exemplo Node.js usa uma variável de ambiente previamente configurada com a URL secreta. Substitua o conteúdo e o link pelos dados adequados da sua rotina; o domínio do exemplo não é um endpoint do Joii.

const webhookUrl = process.env.JOII_WEBHOOK_URL;
if (!webhookUrl) throw new Error("Configure JOII_WEBHOOK_URL");

const response = await fetch(webhookUrl, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Backup concluído",
    text: "Execução backup-2026-09-22-001 concluída.",
    url: "https://painel.example.com/backups/backup-2026-09-22-001"
  })
});
console.log(response.status, await response.json());

O destino e a identidade do aplicativo são definidos pela conexão. O JSON não permite escolher livremente outro canal, autor ou menções. As mensagens do provedor genérico aparecem como Webhook · App; o nome da conexão identifica a origem na tela de gestão.

Entenda a resposta e confira o histórico

O histórico do Joii mostra entregas aceitas e seus estados; uma falha de autenticação anterior à aceitação não aparece como uma mensagem entregue. Uma resposta 202 também não prova que o canal já recebeu a publicação. Use o teste do serviço externo e acompanhe ambos os lados.

Deduplicação e limites para planejar a automação

Corpos idênticos são tratados como duplicatas durante a retenção. Preserve o mesmo corpo ao repetir a mesma ocorrência; inclua uma identidade ou horário no texto quando se tratar de um evento novo. Não gere uma identidade nova a cada tentativa da mesma ocorrência.

O limite atual é de 256 KiB por requisição; títulos aceitam até 240 caracteres e o link HTTPS até 2.048. O ritmo por conexão é de 120 requisições por minuto, com capacidade de rajada de 60; a organização tem um limite compartilhado de 600 por minuto. Esses valores não significam que toda a cota por minuto pode ser enviada de uma só vez. Requisições inválidas e duplicadas também consomem o orçamento após a admissão.

Ao receber 429, o endpoint informa Retry-After: 60; para os casos transitórios tratados como 503, informa 5 segundos. Seu serviço deve decidir quando repetir, com limite de tentativas. Evite loops sem espera e não descarte o resultado de uma falha silenciosamente.

Mantenha a integração sob controle

Pausar uma conexão recusa novos eventos e invalida publicações pendentes daquela geração; ela não guarda uma fila para entregar tudo quando for reativada. Revogar encerra a conexão. Gerar outra URL invalida a anterior imediatamente, então atualize o serviço de origem.

Nesta versão, os destinos são apenas canais internos. A API de entrada não oferece leitura do histórico, administração geral nem ações bidirecionais. Para Sentry e PostHog, prefira as opções específicas do catálogo de integrações, que interpretam os formatos desses provedores.