Saltar para o conteúdo principal
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:
CategoriaEventos
ServiçoCriado, Atualizado, Eliminado
EncomendaCriada, Atualizada, Eliminada
TarefaCriada, Atribuída, Concluída, Atualizada
FaturaEstado alterado
Cliente / UtilizadorNovo cliente adicionado, Cliente/utilizador eliminado
PropostaEnviada, Recebida, Aceite, Rejeitada
TicketCriado, Atribuído, Estado alterado
PagamentoRecebido, Falhado
Pacote de ServiçoCriado, Atualizado, Eliminado

​
Criar um webhook

1

Navegar para Gestão de Webhooks

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

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.
3

Criar um novo webhook

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

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.
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. Pode selecionar eventos de múltiplas categorias — por exemplo, Encomenda: Criada e Fatura: Estado alterado podem ambos 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

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.
1

Abrir o webhook

Na lista de Gestão de Webhooks, clique no webhook que pretende 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 amostra da lista de eventos configurados neste webhook (ex.: Encomenda: Criada).
4

Enviar o payload de teste

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

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
​
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 cabeçalho x-ah-sig do pedido de webhook recebido.
​
secret
string
obrigatório
O segredo do webhook apresentado na página de detalhes do webhook no AgencyHandy.
​
payload
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" }
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 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.