> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acrity.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Configure webhooks de saída para enviar eventos da Acrity a sistemas externos.

Webhooks de saída enviam eventos do workspace para sistemas externos, como ferramentas internas, automações, filas, chatops ou plataformas de observabilidade.

Use `Console > Webhooks` para criar, testar, ativar, desativar, editar e acompanhar entregas.

## Quando usar

Use webhooks quando:

* um sistema externo precisa reagir a eventos da Acrity;
* uma automação interna deve receber notificações;
* você precisa alimentar observabilidade, auditoria ou dashboards;
* integrações via API polling não são desejáveis.

Use `Console > API Keys` quando o sistema externo precisar consultar dados ativamente.

## Quem pode acessar

Admins de workspace normalmente gerenciam webhooks.

## Campos principais

| Campo                   | Para que serve                                                    |
| ----------------------- | ----------------------------------------------------------------- |
| Nome                    | Identifica o webhook no Console.                                  |
| URL                     | Endpoint externo que receberá o evento.                           |
| Método                  | Método HTTP usado na entrega.                                     |
| Content type            | Formato do corpo enviado.                                         |
| Eventos                 | Tipos de evento que disparam o webhook.                           |
| Headers                 | Cabeçalhos adicionais enviados na requisição.                     |
| Headers secretos        | Cabeçalhos cujo valor deve ser protegido e não exibido novamente. |
| HMAC                    | Assinatura para permitir verificação de origem pelo destinatário. |
| Body template           | Modelo opcional para personalizar o payload enviado.              |
| Ignorar verificação SSL | Opção excepcional para ambientes controlados. Evite em produção.  |

## Criar um webhook

<Steps>
  <Step title="Abrir webhooks">
    Acesse `Console > Webhooks`.
  </Step>

  <Step title="Criar novo">
    Escolha `Novo webhook`.
  </Step>

  <Step title="Informar destino">
    Preencha nome, URL, método e content type.
  </Step>

  <Step title="Selecionar eventos">
    Escolha os eventos que devem acionar o webhook.
  </Step>

  <Step title="Configurar segurança">
    Adicione headers necessários e habilite HMAC quando o destinatário puder validar assinatura.
  </Step>

  <Step title="Testar">
    Use o teste ou a prévia da tela antes de ativar em produção.
  </Step>

  <Step title="Salvar">
    Salve e acompanhe as primeiras entregas.
  </Step>
</Steps>

## Headers e segredos

Use headers para enviar tokens, identificadores ou informações exigidas pelo destino.

Boas práticas:

* marque como secreto qualquer header que contenha token ou segredo;
* não coloque segredos no nome do webhook;
* prefira rotação de tokens no sistema destinatário;
* remova headers que não são usados;
* documente internamente o dono do endpoint.

## HMAC

HMAC permite que o sistema destinatário valide que o payload veio da Acrity e não foi alterado em trânsito.

Use HMAC sempre que o destino suportar verificação de assinatura.

Ao habilitar:

1. Gere ou informe um segredo forte.
2. Configure o mesmo segredo no sistema destinatário.
3. Teste uma entrega.
4. Rejeite payloads sem assinatura válida no destino.

## Body template

O body template personaliza o corpo enviado. Use quando o destino espera um formato específico.

Recomendações:

* comece com payload simples;
* valide com a prévia antes de salvar;
* evite incluir dados sensíveis desnecessários;
* mantenha compatibilidade com o sistema destinatário;
* versione mudanças importantes do lado receptor.

## Testar entrega

Antes de ativar um webhook crítico:

* use a ação de teste da tela;
* confirme status de resposta do destino;
* verifique logs do sistema receptor;
* valide assinatura HMAC quando habilitada;
* revise headers e content type;
* confirme que o payload esperado chegou.

## Histórico de entregas

O detalhe do webhook pode exibir histórico de entregas.

Use esse histórico para investigar:

* sucesso ou falha de envio;
* status retornado pelo destino;
* tempo de resposta;
* payload de teste ou entrega quando exibido pela tela;
* erros de conexão, TLS ou validação.

## Ativar e desativar

Desative um webhook quando:

* o destino está em manutenção;
* o endpoint foi substituído;
* há suspeita de segredo exposto;
* a integração está gerando ruído;
* você precisa pausar entregas temporariamente.

Reative apenas depois de validar o destino.

## Problemas comuns

| Sintoma                 | O que verificar                                                                    |
| ----------------------- | ---------------------------------------------------------------------------------- |
| Webhook não salva       | Confira URL, método, content type, eventos e validações da tela.                   |
| Teste retorna erro      | Verifique se o endpoint está acessível publicamente ou pela rede esperada.         |
| Destino rejeita payload | Confira content type, template e schema esperado pelo receptor.                    |
| Assinatura inválida     | Verifique segredo HMAC nos dois lados e se o receptor usa o payload bruto correto. |
| Erro TLS                | Corrija certificado do destino. Evite ignorar SSL em produção.                     |

## Segurança

Webhooks podem enviar dados operacionais para fora da Acrity. Configure apenas destinos confiáveis e revise periodicamente quais eventos estão ativos.

Detalhes sobre tratamento de dados ficam em `Segurança > Tratamento de dados`.