Pular para o conteúdo principal
Os webhooks permitem que o AgencyHandy envie dados para seus sistemas externos no momento em que algo muda — sem necessidade de polling. Quando um evento configurado é acionado (por exemplo, um pedido é atualizado ou um ticket é criado), o AgencyHandy envia uma requisição HTTP POST com um payload JSON para a URL do endpoint que você especificar. Isso facilita manter ferramentas externas como CRMs, sistemas de faturamento ou dashboards personalizados sincronizados com seu workspace do AgencyHandy em tempo real.
Workspaces no plano Business Pro suportam até 30.000 eventos de webhook por período de faturamento. Verifique os limites do seu plano antes de configurar automações de alto volume.

​
Eventos suportados

Você pode inscrever um webhook em qualquer combinação dos seguintes eventos:
CategoriaEventos
ServiçoCriado, Atualizado, Excluído
PedidoCriado, Atualizado, Excluído
TarefaCriada, Atribuída, Concluída, Atualizada
FaturaStatus alterado
Cliente / UsuárioNovo cliente adicionado, Cliente/usuário excluído
PropostaEnviada, Recebida, Aceita, Rejeitada
TicketCriado, Atribuído, Status alterado
PagamentoRecebido, Com falha
Pacote de ServiçoCriado, Atualizado, Excluído

​
Criar um webhook

1

Navegar até o Gerenciamento de Webhooks

Na barra lateral esquerda, acesse Integrações → Gerenciamento de Webhooks.
2

Autenticar seu token

Clique no botão Gerenciamento para autenticar seu token de webhook. Esse token é usado para assinar os payloads enviados para que você possa verificar que se originaram do AgencyHandy.
3

Criar um novo webhook

Clique em Criar Novo Webhook para abrir o formulário de configuração do webhook.
4

Inserir a URL do endpoint

No campo URL do Endpoint, insira a URL do sistema externo que deve receber os dados do webhook. Deve ser um endpoint POST acessível publicamente.
5

Selecionar o tipo de conteúdo

Escolha JSON como tipo de conteúdo. O AgencyHandy envia todos os payloads de webhook como application/json.
6

Selecionar os eventos do webhook

Escolha todos os eventos que devem acionar este webhook. Você pode selecionar eventos de múltiplas categorias — por exemplo, Pedido: Criado e Fatura: Status alterado podem apontar para o mesmo endpoint.
7

Ativar o webhook

Ative o botão de opção Ativo. Quando ativo, o AgencyHandy entrega payloads para todos os eventos selecionados ao seu endpoint em tempo real.
8

Salvar a configuração

Revise suas configurações e clique em Salvar. O webhook aparece na lista e começa a entregar eventos imediatamente.

​
Testar um webhook

Após criar um webhook, envie um payload de teste para confirmar que seu endpoint está acessível e processando dados corretamente.
1

Abrir o webhook

Na lista de Gerenciamento de Webhooks, clique no webhook que deseja testar.
2

Clicar em Testar Evento

Clique no botão Testar Evento na página de detalhes do webhook.
3

Selecionar um evento de teste

Escolha um evento de exemplo da lista de eventos configurados neste webhook (ex.: Pedido: Criado).
4

Enviar o payload de teste

Clique em Enviar. O AgencyHandy publica um payload de exemplo na URL do seu endpoint.
5

Verificar o resultado

Verifique em seu sistema externo se o payload de teste chegou e foi processado conforme esperado. De volta ao AgencyHandy, clique no webhook para revisar seu histórico — você pode ver a requisição completa, a resposta que seu endpoint retornou, e reenviar qualquer evento passado se necessário.
Use uma ferramenta como Webhook.site ou RequestBin como endpoint temporário durante a configuração para inspecionar o formato exato do payload antes de conectar seu sistema real.

​
Autenticar payloads de webhook

Toda requisição de webhook enviada pelo AgencyHandy inclui um header de assinatura que seu endpoint pode usar para verificar se o payload é genuíno e não foi adulterado.

​
Header de assinatura

x-ah-sig: <signature>
O AgencyHandy adiciona este header a cada requisição de webhook. Extraia o valor das requisições recebidas e passe-o para o endpoint de verificação.

​
Verificar uma assinatura de webhook

Envie a seguinte requisição para confirmar que um payload é autêntico: 
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
​
webhookId
string
obrigatório
O ID do webhook que recebeu o evento. Encontre-o na página de detalhes do webhook no AgencyHandy.
​
signature
string
obrigatório
O valor do header x-ah-sig da requisição de webhook recebida.
​
secret
string
obrigatório
O segredo do webhook exibido na página de detalhes do webhook no AgencyHandy.
​
payload
object
obrigatório
O corpo JSON bruto recebido da requisição de webhook do AgencyHandy.
const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';

const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',   // value of x-ah-sig header
  secret: 'your_webhook_secret',
  payload: {},                   // the parsed JSON body from AgencyHandy
};

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(postData),
});

const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }
Respostas
​
verification_status
string
SUCCESS quando a assinatura é válida. FAILED quando a verificação falha (HTTP 403).
Success (200)
{
  "verification_status": "SUCCESS"
}
Failure (403)
{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}
Mantenha o segredo do seu webhook em sigilo. Renove-o periodicamente e atualize sua lógica de verificação imediatamente após a renovação. Nunca o exponha em código do lado do cliente ou em repositórios públicos.

​
Notas importantes

  • A URL do seu endpoint deve ser uma URL HTTPS POST acessível publicamente.
  • Se o seu endpoint estiver temporariamente indisponível, verifique o painel de histórico do webhook no AgencyHandy — você pode reenviar qualquer evento passado diretamente de lá.
  • Monitore regularmente a atividade dos webhooks para detectar falhas de entrega ou tentativas de acesso não autorizado.
  • Webhooks que falham repetidamente podem ser pausados pelo AgencyHandy — revise os logs de entrega para identificar problemas precocemente.