Gestão de Webhooks: Criar, Testar e Autenticar

Os webhooks permitem que o AgencyHandy envie dados para os seus sistemas externos no momento em que algo muda — sem necessidade de polling. Quando um evento configurado é acionado (por exemplo, uma encomenda é atualizada ou um ticket é criado), o AgencyHandy envia um pedido HTTP POST com um payload JSON para o URL do endpoint que especificar. Isto facilita a sincronização de ferramentas externas como CRMs, sistemas de faturação ou dashboards personalizados com o seu workspace AgencyHandy em tempo real.

Os workspaces do plano Business Pro suportam até 30.000 eventos de webhook por período de faturação. Verifique os limites do seu plano antes de configurar automatizações de alto volume.

Eventos suportados

Pode subscrever um webhook para qualquer combinação dos seguintes eventos:

Categoria	Eventos
Serviço	Criado, Atualizado, Eliminado
Encomenda	Criada, Atualizada, Eliminada
Tarefa	Criada, Atribuída, Concluída, Atualizada
Fatura	Estado alterado
Cliente / Utilizador	Novo cliente adicionado, Cliente/utilizador eliminado
Proposta	Enviada, Recebida, Aceite, Rejeitada
Ticket	Criado, Atribuído, Estado alterado
Pagamento	Recebido, Falhado
Pacote de Serviço	Criado, Atualizado, Eliminado

Criar um webhook

Navegar para Gestão de Webhooks

Na barra lateral esquerda, aceda a Integrações → Gestão de Webhooks.

Autenticar o seu token

Clique no botão Gestão para autenticar o seu token de webhook. Este token é utilizado para assinar os payloads enviados para que possa verificar que têm origem no AgencyHandy.

Criar um novo webhook

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

Introduzir o URL do endpoint

No campo URL do Endpoint, introduza o URL do sistema externo que deve receber os dados do webhook. Este deve ser um endpoint POST acessível publicamente.

Selecionar o tipo de conteúdo

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

Selecionar os eventos do webhook

Escolha todos os eventos que devem acionar este webhook. Pode selecionar eventos de múltiplas categorias — por exemplo, Encomenda: Criada e Fatura: Estado alterado podem ambos apontar para o mesmo endpoint.

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.

Guardar a configuração

Reveja as suas definições e clique em Guardar. 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 o seu endpoint é acessível e está a processar os dados corretamente.

Abrir o webhook

Na lista de Gestão de Webhooks, clique no webhook que pretende testar.

Clicar em Testar Evento

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

Selecionar um evento de teste

Escolha um evento de amostra da lista de eventos configurados neste webhook (ex.: Encomenda: Criada).

Enviar o payload de teste

Clique em Enviar. O AgencyHandy publica um payload de amostra no URL do seu endpoint.

Verificar o resultado

Verifique o seu sistema externo para confirmar que o payload de teste chegou e foi processado conforme esperado. No AgencyHandy, clique no webhook para rever o seu histórico — pode ver o pedido completo, a resposta que o seu endpoint devolveu, e reenviar qualquer evento anterior se necessário.

Utilize uma ferramenta como Webhook.site ou RequestBin como endpoint temporário durante a configuração para inspecionar o formato exato do payload antes de ligar ao seu sistema real.

Autenticar payloads de webhook

Cada pedido de webhook enviado pelo AgencyHandy inclui um cabeçalho de assinatura que o seu endpoint pode utilizar para verificar que o payload é genuíno e não foi adulterado.

Cabeçalho de assinatura

x-ah-sig: <signature>

O AgencyHandy adiciona este cabeçalho a cada pedido de webhook. Extraia o valor dos pedidos recebidos e passe-o para o endpoint de verificação.

Verificar uma assinatura de webhook

Envie o seguinte pedido para confirmar que um payload é autêntico:

POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json

string

obrigatório

O ID do webhook que recebeu o evento. Encontre-o na página de detalhes do webhook no AgencyHandy.

string

obrigatório

O valor do cabeçalho x-ah-sig do pedido de webhook recebido.

string

obrigatório

O segredo do webhook apresentado na página de detalhes do webhook no AgencyHandy.

object

obrigatório

O corpo JSON bruto recebido do pedido 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" }

curl -X POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature \
  -H "Content-Type: application/json" \
  -d '{
    "webhookId": "your_webhook_id",
    "signature": "your_signature",
    "secret": "your_webhook_secret",
    "payload": {}
  }'

Respostas

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 webhook confidencial. Renove-o periodicamente e atualize a sua lógica de verificação imediatamente após a renovação. Nunca o exponha em código do lado do cliente ou repositórios públicos.

Notas importantes

O URL do seu endpoint deve ser um URL HTTPS POST publicamente acessível.
Se o seu endpoint estiver temporariamente indisponível, verifique o painel de histórico do webhook no AgencyHandy — pode reenviar qualquer evento anterior diretamente a partir daí.
Monitorize regularmente a atividade dos webhooks para detetar entregas falhadas ou tentativas de acesso não autorizado.
Os webhooks que falham repetidamente podem ser pausados pelo AgencyHandy — reveja os registos de entrega para detetar problemas precocemente.

Começar

Configuração do Espaço de Trabalho

CRM

Serviços & Encomendas

Propostas & Faturas

Equipa & Tarefas

Formulários & Ficheiros

Conta & Faturação

Pagamentos

Integrações

Gestão de Webhooks: Criar, Testar e Autenticar

Eventos suportados

Criar um webhook

Testar um webhook

Autenticar payloads de webhook

Cabeçalho de assinatura

Verificar uma assinatura de webhook

Notas importantes

​Eventos suportados

​Criar um webhook

​Testar um webhook

​Autenticar payloads de webhook

​Cabeçalho de assinatura

​Verificar uma assinatura de webhook

​Notas importantes

Eventos suportados

Criar um webhook

Testar um webhook

Autenticar payloads de webhook

Cabeçalho de assinatura

Verificar uma assinatura de webhook

Notas importantes