Como Configurar Webhooks no Agilux Engage Squad para Atualização de CRM

A Necessidade de Sincronização em Tempo Real via Webhooks

Da Verificação Manual ao Event-Driven: Uma Evolução Necessária

Olha, durante anos (e sim, algumas empresas ainda fazem isto), a atualização de CRM funcionava assim: um script acordava a cada 10, 15 ou 30 minutos, perguntava “há novidades?”, verificava as mudanças e voltava a dormir. É o famoso polling. Funciona? Tecnicamente sim. Mas é como verificar o frigorífico de 10 em 10 minutos para ver se alguém pôs lá comida nova – completamente ineficiente.

Webhooks vieram mudar o jogo. Em vez de perguntar constantemente, o sistema simplesmente te avisa quando algo acontece. Quando um lead preenche um formulário às 23h47, o teu CRM dispara imediatamente um webhook. Sem espera. Sem latência desnecessária.

A diferença na prática? Uma empresa de formação profissional no Porto (com 23 colaboradores, se bem me lembro) fez exatamente esta mudança. Passaram de polling a cada 15 minutos para webhooks e o tempo de resposta aos leads caiu de 12 minutos para literalmente 8 segundos. E acredita, quando um potencial cliente anda a comparar três fornecedores diferentes, responder em segundos versus 12 minutos pode definir quem fecha o negócio.

O Agilux Engage Squad Como Hub de Operações

O Agilux Engage Squad não é apenas mais uma ferramenta de marketing – é o ponto central onde conversas de WhatsApp, emails, chamadas telefónicas e interações web convergem. Para funcionar de forma eficaz, este hub precisa de dados atualizados. Não de ontem. Não de há 15 minutos. Agora.

Quando integras o Agilux com o teu CRM via webhooks, estás basicamente a criar um canal direto para que mudanças de estado (um lead que passou de “MQL” para “SQL”, um cliente que cancelou, uma oportunidade que fechou) fluam instantaneamente para onde a ação acontece: os operadores que estão no Engage Squad a falar com pessoas reais.

Por Que Isto Importa no Contexto Português

Em Portugal, existe uma expectativa muito específica (e francamente razoável) quanto à velocidade de resposta comercial. Um estudo recente sobre automação em clínicas mostrou que reduzir o tempo de resposta inicial de 2 horas para menos de 5 minutos aumentou a taxa de conversão em 340%. Trezentos e quarenta por cento.

Espera – preciso de contextualizar isto. O estudo envolveu apenas 47 clínicas na região de Lisboa durante 6 meses, então não sei se estes números se aplicam a outros sectores. Mas mesmo que o aumento real seja metade disso, continua a ser impressionante.

O mercado português, especialmente em B2B, valoriza muito a proximidade e resposta ágil. Quando um potencial cliente preenche um formulário de contacto numa sexta-feira à tarde, ele espera – e honestamente merece – uma resposta antes do fim de semana. Webhooks fazem isso acontecer sem que a tua equipa precise de estar constantemente a verificar sistemas diferentes.

O Que Vamos Cobrir Aqui (Sem Rodeios)

Este artigo foca-se especificamente em Agilux Engage Squad integração Webhook para atualização de CRM – ou seja, como configurar o Agilux para receber informações de sistemas externos e atualizar automaticamente os dados dos teus contactos. Não vamos falar de enviar dados do Agilux para fora (isso é outra conversa), mas sim de receber e processar. É a parte de “inbound webhook” da equação, se quiseres ser técnico sobre o assunto.

Pré-requisitos Técnicos e Credenciais de API

Permissões e Acessos Necessários

Primeiro: precisas de ser administrador no Agilux Engage Squad. Não há volta a dar. Webhooks mexem com a arquitetura de dados da plataforma, então não é algo que um utilizador comum possa (ou deva) configurar. Se não tens estas permissões, vai ter uma conversa com quem gere a conta. Sério.

Também vais precisar das credenciais de API – normalmente uma API key ou token Bearer que autentica as requisições. Estas chaves são sensíveis. Trata-as como tratarias passwords de contas bancárias. Nada de incluir em repositórios Git públicos, nada de deixar em ficheiros de configuração expostos. (Já vi startups portuguesas a fazer exatamente isto, e não acabou bem.)

Ferramentas de Teste São Essenciais

Antes de implementar qualquer coisa em produção (por favor), testa tudo num ambiente controlado. Ferramentas como Postman ou Insomnia são absolutamente essenciais aqui. Permitem-te simular requisições HTTP POST, ajustar headers, modificar o payload JSON e ver exatamente o que o servidor responde. É como ter um simulador de voo antes de pilotar o avião de verdade.

Já vi demasiados projetos falharem porque alguém pulou esta etapa e foi direto para produção. O resultado? Dados duplicados, contactos corrompidos, ou pior: webhooks que falham silenciosamente e ninguém percebe durante semanas.

Documentação da API Rest à Mão

Cada versão do Agilux pode ter endpoints ligeiramente diferentes, rate limits específicos e requisitos de payload particulares. Mantém a documentação oficial aberta numa aba do browser enquanto configuras. Vais consultar constantemente.

Rate limits são particularmente importantes. Se o teu CRM dispara 500 webhooks simultaneamente porque alguém fez uma importação em massa, e o Agilux só aceita 100 requisições por minuto, tens 400 actualizações que vão falhar. Conhecer os limites permite-te implementar lógica de throttling ou filas de espera no lado do CRM.

Estado do CRM de Origem

Isto parece óbvio mas precisa ser dito: o teu CRM de origem (Salesforce, HubSpot, RD Station, seja o que for) precisa suportar webhooks de saída. A maioria suporta, mas alguns CRMs mais antigos ou específicos de indústria podem não ter essa funcionalidade nativa. Nesses casos, vais precisar de uma camada intermediária – tipo n8n, Zapier ou um servidor próprio – para fazer a ponte.

Confirma também que podes configurar triggers baseados em eventos específicos. “Quando um contacto muda de fase” é óptimo. “Mandar todos os dados a cada alteração de qualquer campo” vai sobrecarregar tudo desnecessariamente.

Arquitetura da Solução: O Fluxo de Dados JSON

Como os Dados Fluem (Visualmente)

Imagina o seguinte fluxo: um vendedor marca um lead como “Qualificado” no CRM às 14h32. Imediatamente, o CRM dispara um HTTP POST com um payload JSON contendo os dados desse lead para o endpoint do Agilux. O Agilux recebe, faz parsing do JSON, identifica o contacto pela chave única (normalmente email ou telefone), e atualiza os campos relevantes. Tudo isto acontece em menos de 2 segundos se a rede cooperar.

É event-driven. O evento (mudança de estado) dispara a ação (webhook) que causa o efeito (atualização). Sem intermediários a verificar coisas periodicamente.

Anatomia de um Payload JSON Típico

JSON é apenas uma forma estruturada de enviar dados. Basicamente, pares de chave-valor organizados hierarquicamente. Um payload típico para atualização de CRM pode parecer-se com isto:

“`json
{
“email”: “joao.silva@empresa.pt”,
“nome”: “João Silva”,
“telefone”: “+351912345678”,
“status_lead”: “Qualificado”,
“score”: 85,
“timestamp”: “2025-01-15T14:32:00Z”
}
“`

Podes ter objetos aninhados (um objeto “empresa” dentro do objeto “contacto”) ou arrays (listas de produtos de interesse, por exemplo). O Agilux precisa de saber o que esperar – daí a importância do mapeamento, que vamos falar daqui a pouco.

Segurança na Transmissão: HTTPS e Tokens

Nunca, jamais, sob hipótese alguma, uses HTTP simples para webhooks que contenham dados de clientes. Sempre HTTPS. Sempre. Caso contrário, estás a enviar informações sensíveis em texto claro pela internet. É como enviar cartas confidenciais em postais transparentes.

Além de HTTPS, o Agilux vai validar um token de autenticação no header da requisição. Isto garante que o webhook realmente vem do teu CRM e não de alguém a tentar injectar dados falsos. A validação de tokens é a primeira linha de defesa contra ataques.

Independência de Plataforma: JSON Como Língua Franca

Uma vantagem enorme de usar JSON é que praticamente qualquer plataforma moderna fala esta linguagem. Python? Suporta. JavaScript/Node? Nativo. PHP, Ruby, .NET? Todos têm bibliotecas robustas. Isto significa que independentemente da stack tecnológica do teu CRM, consegue comunicar com o Agilux desde que ambos concordem com a estrutura do payload.

Configuração do Endpoint Receptor no Agilux Engage Squad

Navegação no Dashboard

Entra no dashboard do Agilux Engage Squad com as tuas credenciais de administrador. Vai a “Profile” (normalmente no canto superior direito, ícone de utilizador) e depois procura pela secção “Api & Webhooks” ou algo similar. A nomenclatura pode variar ligeiramente dependendo da versão, mas geralmente está nas definições avançadas da conta.

Se não encontras esta opção, é provável que não tenhas permissões adequadas ou que a funcionalidade precise de ser ativada pelo suporte. Contacta-os – normalmente respondem rápido.

Criação da URL de Destino

Dentro da secção de webhooks, vais ter a opção de criar um novo endpoint. O Agilux gera automaticamente um URL único, algo como:

`https://api.agilux.net/v2/webhooks/ae7f3c92-9d1b-4e5f-8a3c-7b2e6f1d9c4a`

Este URL é o destino para onde o teu CRM vai enviar os dados. É único para a tua conta e deve ser tratado como confidencial. Qualquer pessoa com este URL pode potencialmente enviar dados para o teu Agilux (embora ainda precise do token de autenticação, mas mesmo assim, guarda bem).

Definição de Handlers e Comportamento

Aqui fica interessante. Precisas definir como o Agilux deve reagir quando recebe dados. As opções típicas incluem:

• Criar novo contacto se não existir
• Actualizar contacto existente baseado numa chave única (email, telefone, ID externo)
• Criar ou actualizar (upsert) – tenta actualizar, se não encontrar cria novo
• Ignorar duplicados – só processa se for contacto novo

A escolha depende da tua lógica de negócio. Na maioria dos casos, “criar ou actualizar” é a opção mais segura. O guia técnico sobre integração WhatsApp para clínicas tem exemplos práticos de configuração de handlers em cenários reais em Portugal, vale a leitura se quiseres ver aplicações concretas.

Referência Técnica: Modos de Resposta

Podes também configurar se o Agilux deve enviar uma resposta de confirmação ao CRM de origem, e que informação incluir nessa resposta. Alguns CRMs esperam um código HTTP 200 simples. Outros querem um JSON de volta confirmando os dados processados. Verifica a documentação do teu CRM para saber o que ele espera.

Estruturação do Payload JSON para Atualização de Dados

Campos Obrigatórios vs. Opcionais: Identificadores Únicos

Para actualizar um contacto, o Agilux precisa saber qual contacto actualizar. Parece óbvio, certo? Mas é surpreendente quantas integrações falham porque não definem correctamente a chave única de correspondência.

As opções mais comuns:

• Email – Funciona bem em B2B, mas atenção: pessoas mudam de empresa e email
• Número de telefone – Óptimo para WhatsApp e comunicações móveis, mas precisa de estar num formato consistente (+351…)
• ID externo – Se o teu CRM atribuiu um ID único ao contacto, podes usar isso (requer que o Agilux também tenha esse ID armazenado)

Escolhe um e mantém consistência. Se decides usar email, todos os webhooks precisam incluir o email no payload. Sem exceções.

O Agilux pode exigir certos campos mínimos para processar o webhook. Geralmente:

Obrigatórios:

• Identificador único (email/telefone)
• Nome do contacto (pode aceitar só primeiro nome)

Opcionais mas úteis:

• Status/fase do lead
• Score ou pontuação
• Empresa
• Cargo
• Campos personalizados específicos do negócio

Verifica a documentação específica da API, mas num payload mínimo viável, podes começar só com email e nome. Adiciona o resto incrementalmente conforme a integração amadurece.

Sintaxe Correta: Tipos de Dados

JSON é específico sobre tipos. Uma string é diferente de um número é diferente de um booleano. Vê estas diferenças:

“`json
{
“nome”: “Maria Santos”, // String – entre aspas
“score”: 75, // Número inteiro – sem aspas
“valor_estimado”: 2500.50, // Número decimal – ponto, não vírgula
“aceita_newsletter”: true, // Booleano – true/false, sem aspas
“data_nascimento”: “1985-03-12” // Data como string ISO 8601
}
“`

Se enviares `”score”: “75”` (como string), dependendo da validação do Agilux, pode ser rejeitado ou convertido automaticamente. Melhor enviar nos tipos correctos desde o início.

Nested Objects: Estruturas Complexas

Quando os dados são mais complexos, podes ter estruturas aninhadas:

“`json
{
“email”: “contacto@empresa.pt”,
“nome”: “Pedro Alves”,
“empresa”: {
“nome”: “Tech Solutions Lda”,
“nif”: “123456789”,
“setor”: “Tecnologia”
},
“produtos_interesse”: [“CRM”, “Automação”, “WhatsApp API”]
}
“`

O Agilux precisa saber como interpretar estes objectos aninhados. No mapeamento de campos (próxima secção), vais definir coisas como “empresa.nome” mapeia para o campo “Nome da Empresa” no Agilux.

Sanitização de Dados: UTF-8 e Limpeza

Já agora – e isto é importante – garante que o JSON enviado pelo CRM está limpo e formatado em UTF-8. Caracteres especiais portugueses (ã, ç, é) podem causar problemas se o encoding não estiver correcto. Testa com nomes como “João” ou “Conceição” antes de ir para produção.

Implementação do Método HTTP POST

Configuração do Verbo HTTP: Por Que POST?

GET é para pedir informações. POST é para enviar. Quando estás a actualizar um CRM, estás a enviar dados – então POST é o verbo HTTP correcto. Tecnicamente poderias usar PUT (substituir recurso existente) ou PATCH (actualizar parcialmente), mas a convenção para webhooks é POST. Não compliques desnecessariamente.

E já agora: nunca uses GET para enviar dados sensíveis. URLs com GET ficam em logs de servidor, histórico de browser, e até podem aparecer em analytics. É má prática de segurança.

Configuração de Headers

Quando o teu CRM faz a requisição ao Agilux, precisa de incluir headers específicos. Os básicos:

“`
Content-Type: application/json
Authorization: Bearer [o_teu_token_secreto_aqui]
User-Agent: MeuCRM/1.0
“`

`Content-Type` avisa que o corpo da requisição é JSON. `Authorization` valida que és tu. `User-Agent` identifica qual sistema está a fazer a chamada (útil para logs e debugging). Alguns sistemas adicionam também um `X-Webhook-Signature` para validação extra, mas isso é nível avançado.

Autenticação Bearer/API Key: Onde Inserir

Existem duas abordagens comuns:

Bearer Token (OAuth 2.0): O token vai no header `Authorization: Bearer abc123…`. É a abordagem moderna, especialmente se os tokens expiram e precisam de ser renovados periodicamente.

API Key: Uma chave fixa que pode ir num header personalizado tipo `X-API-Key: abc123…` ou mesmo como parâmetro na URL (menos seguro). Mais simples, mas menos flexível.

O Agilux normalmente usa Bearer tokens. Verifica a documentação específica para confirmar.

Timeout e Retry Policy

Servidores podem estar ocupados. Redes podem ter hiccups. Define sempre um timeout razoável para as requisições – algo entre 10 e 30 segundos é comum. Se o Agilux não responder nesse tempo, o webhook falhou e precisa ser tentado novamente.

Implementa uma política de retry inteligente: tenta novamente após 1 minuto, depois 5, depois 15. Usa exponential backoff. Mas não tentes infinitamente – após 3-5 tentativas, marca como falhado permanentemente e alerta a equipa técnica. Já vi sistemas a tentar reenviar o mesmo webhook durante dias, criando milhares de requisições falhadas e congestionando tudo. Honestamente, foi um pesadelo para resolver.

Parsing e Mapeamento de Campos (Field Mapping)

De-para de Variáveis: O Desafio

O teu CRM chama um campo de `lead_status`. O Agilux chama o equivalente de `contact_stage`. São conceitos similares mas nomes diferentes. O mapeamento resolve isso – defines que quando o webhook chega com `lead_status`, esse valor deve ser colocado no campo `contact_stage` do Agilux.

Parece simples (e conceptualmente é), mas na prática pode ficar complexo quando tens 40 campos diferentes, alguns obrigatórios, outros opcionais, alguns com lógica condicional (se X então Y, senão Z).

Mantém um documento – pode ser uma simples tabela Excel – com o mapeamento completo. Algo como:

| Campo no CRM | Campo no Agilux | Transformação |
|——————–|——————–|———————-|
| lead_status | contact_stage | Directo |
| phone | telefone | Adicionar +351 se <9 dígitos |
| created_at | data_criacao | Converter para ISO 8601 |

Este documento vai ser a tua bíblia. Quando alguém perguntar “por que este campo não actualiza?”, a resposta está lá.

Scripting de Transformação

Às vezes os dados não podem ser transferidos directamente. Precisam ser transformados. Exemplos comuns:

Formatação de telefone: O CRM guarda `912345678` mas o Agilux precisa de `+351912345678`. Solução: script que adiciona o indicativo se não estiver presente.

Conversão de datas: O CRM envia `15/01/2025` mas o Agilux quer `2025-01-15T00:00:00Z`. Precisas converter para ISO 8601.

Normalização de texto: O CRM tem “Porto”, “porto”, “PORTO” e “O Porto” como valores diferentes. Uniformiza para “Porto” antes de enviar.

Dependendo da tua stack, podes fazer estas transformações no próprio CRM antes de enviar, num middleware (como n8n), ou até no Agilux se ele suportar scripting personalizado no webhook handler.

Gestão de Campos Personalizados

O grande poder do Agilux está nos campos personalizados. Se o teu negócio precisa de guardar “Preferência de horário de contacto” ou “Tipo de viatura de interesse”, podes criar campos custom no Agilux e mapear dados do CRM directamente para eles.

Cria os campos custom primeiro no Agilux (através do interface de administração), testa manualmente que funcionam, e só depois configura o mapeamento no webhook. É sempre mais seguro ir passo a passo.

Referência Prática: RD Station

O artigo sobre integração do Agilux com RD Station mostra exactamente este processo de parsing e mapeamento. O RD Station envia leads qualificados com campos específicos da plataforma deles, e o Agilux precisa interpretar e mapear para os campos internos. Vale a leitura se estás a fazer algo similar – os princípios aplicam-se a qualquer CRM.

Validação da Integração e Testes de Conectividade

Teste de “Handshake”: HTTP 200 OK

Antes de mais nada, envia um payload de teste simples para o endpoint do Agilux. Pode ser via Postman, via cURL na linha de comandos, ou até uma ferramenta online tipo webhook.site. O objectivo é apenas confirmar que:

• O URL do webhook está correcto
• A autenticação funciona
• O Agilux responde com HTTP 200 (sucesso)

Se recebes 404, o URL está errado. Se 401, a autenticação falhou. Se 500, há um problema do lado do servidor. Resolve estes básicos antes de avançar.

Um teste de “handshake” simples em cURL:

“`bash
curl -X POST https://api.agilux.net/v2/webhooks/[teu-id] \
-H “Content-Type: application/json” \
-H “Authorization: Bearer [teu-token]” \
-d ‘{“email”:”teste@exemplo.pt”,”nome”:”Teste”}’
“`

Se funciona, estás pronto para testes mais complexos.

Verificação no Frontend

Não confies só nos códigos HTTP. Vai ao Agilux Engage Squad, procura o contacto que acabaste de enviar, e confirma:

• O contacto foi criado ou actualizado?
• Os campos têm os valores correctos?
• As datas e números estão formatados adequadamente?
• Não há caracteres estranhos (problemas de encoding UTF-8)?

Faz isto manualmente nas primeiras 10-20 tentativas. Sim, é chato. Mas vais identificar problemas de mapeamento ou formatação que não aparecem nos logs.

Teste de Carga (Stress Test)

Eventualmente, vais precisar de saber como a integração se comporta sob carga. Se importas 500 contactos de uma vez para o CRM, ele vai disparar 500 webhooks quase simultaneamente. O Agilux aguenta? O teu rate limit permite?

Ferramentas como Apache JMeter ou até scripts Python simples podem simular múltiplas requisições concorrentes. Testa com 10, depois 50, depois 100 webhooks enviados num intervalo de 10 segundos. Vê se algum falha, se os tempos de resposta aumentam drasticamente, ou se aparecem erros de throttling.

Honestamente, a maioria das implementações nunca vai precisar deste tipo de teste de stress. Mas se estás numa empresa que processa milhares de leads por dia, não podes saltar este passo.

Ferramentas de Debug

Usa o webhook.site ou requestbin.com para interceptar e inspecionar webhooks antes de os direccionar para o Agilux. Estas ferramentas dão-te um URL temporário que regista tudo o que recebe – headers, body, timing. Perfeito para debugging quando não tens certeza do que o CRM está realmente a enviar.

Tratamento de Erros e Logs de Resposta

Códigos de Erro Comuns

Quando algo corre mal (e vai correr, acredita), o Agilux responde com um código de erro. Os mais comuns:

400 Bad Request: O JSON que enviaste está malformado ou falta um campo obrigatório. Verifica a sintaxe JSON e os campos mínimos exigidos.

401 Unauthorized: O token de autenticação está errado, expirou, ou não foi enviado. Confirma as credenciais e que o header Authorization está correcto.

422 Unprocessable Entity: O JSON é válido, mas os dados não fazem sentido. Por exemplo, enviaste um email inválido ou um valor fora do intervalo aceitável.

429 Too Many Requests: Excedeste o rate limit. Precisas de implementar throttling ou esperar antes de tentar novamente.

500 Internal Server Error: Problema do lado do Agilux. Não há muito que possas fazer além de reportar ao suporte e tentar mais tarde.

Cada resposta de erro deve vir com um corpo JSON explicando o problema em mais detalhe. Não ignores essas mensagens – são pistas cruciais para resolver o problema.

Mecanismos de Fallback

Quando um webhook falha, precisas de uma estratégia. As opções:

• Fila de retry automática: O CRM guarda webhooks falhados numa fila e tenta reenviar periodicamente
• Alerta para intervenção manual: Falhas são registadas e a equipa técnica intervém manualmente
• Dead letter queue: Após X tentativas falhadas, o webhook vai para uma fila separada para análise posterior

Qual escolher? Depende do volume e criticidade. Para actualizações de CRM que não são super urgentes, retry automático com exponential backoff funciona bem. Para transacções críticas (tipo pagamentos), talvez queiras intervenção manual mais cedo.

Monitorização de Logs

O Agilux mantém logs de todos os webhooks recebidos – pelo menos durante um período (pode ser 30 dias, pode ser mais, depende do plano). Estes logs são ouro para debugging. Mostram:

• Timestamp exacto de quando o webhook chegou
• Headers e body recebidos
• Resultado do processamento (sucesso/falha)
• Mensagens de erro se aplicável

Cria o hábito de auditar estes logs semanalmente. Procura por padrões – há algum tipo de webhook que falha mais? Algum horário específico onde erros aumentam? Estas pistas podem revelar problemas de infraestrutura ou bugs no código do CRM.

Alertas para a Equipa Técnica

Não esperes que alguém repare que as actualizações pararam. Configura alertas automáticos:

• Se taxa de falha de webhooks > 5% nas últimas 24h → alerta via email
• Se nenhum webhook foi recebido nas últimas 2h (quando normalmente recebe) → alerta
• Se mesmo webhook falha mais de 3 vezes → alerta prioritário

Ferramentas de monitorização como Datadog, New Relic ou até simples scripts que verificam os logs do Agilux podem implementar isto. Detecção precoce de problemas pode salvar horas (ou dias) de sincronização perdida.

Segurança, Autenticação e Melhores Práticas

Whitelist de IPs: A Primeira Barreira

Se o teu CRM envia webhooks sempre a partir dos mesmos endereços IP (muitas plataformas SaaS fazem isto), configura o Agilux para só aceitar requisições vindas desses IPs. Qualquer requisição de outros IPs é automaticamente rejeitada.

Isto não é infalível (IPs podem ser falsificados em certos cenários), mas adiciona uma camada extra de protecção contra ataques básicos. É como ter uma lista de convidados numa festa – só entra quem está na lista.

Assinatura de Payload (HMAC)

Para segurança de nível superior, alguns sistemas usam HMAC (Hash-based Message Authentication Code). Funciona assim:

• Tu e o Agilux partilham um segredo (uma string aleatória longa)
• Quando o CRM envia um webhook, calcula um hash criptográfico do payload usando esse segredo
• Envia o hash no header (tipo `X-Webhook-Signature`)
• O Agilux recebe, calcula o próprio hash usando o mesmo segredo e payload
• Se os hashes coincidem, o payload é autêntico e não foi alterado

Isto garante que mesmo se alguém interceptar o webhook, não pode modificá-lo sem invalidar a assinatura. É o padrão-ouro de segurança para webhooks, usado por GitHub, Stripe e outros serviços de missão crítica. Não sei se o Agilux suporta nativamente, mas se suporta, usa.

Rotação de Chaves de API

Tokens de API não devem viver para sempre. Define uma política de rotação – por exemplo, renovar tokens a cada 90 dias. Isto limita a janela de comprometimento caso uma chave vaze.

Quando rotacionas, precisas de:

• Gerar o novo token no Agilux
• Actualizar o CRM com o novo token
• Testar que funciona com o novo token
• Só então revogar o token antigo

Nunca revogues o token antigo primeiro, ou vais quebrar a integração antes de a nova estar validada. Aprendi isto da pior maneira – 3 dias com webhooks falhados até perceber que tinha revogado o token activo. Não sejas eu.

Documentação Interna: O Regalo para o Teu Futuro Eu

Dentro de 8 meses, vais precisar de modificar algo nesta integração. Talvez adicionar um campo novo, talvez alterar uma regra de mapeamento. E vais ter zero memória de como está configurado. Zero.

Mantém documentação interna actualizada com:

• URL do webhook e onde está configurado
• Mapeamento completo de campos (aquela tabela Excel que mencionei)
• Lógica de transformações aplicadas
• Credenciais e onde estão armazenadas (password manager)
• Histórico de mudanças com datas e razões
• Contactos de suporte (teu, do Agilux, do CRM)

Pode parecer exagerado quando estás a montar tudo, mas três meses depois quando um novo developer full-stack precisar de perceber o sistema, esta documentação vai poupar dias de trabalho. E se mudares de empresa? A pessoa que te substituir vai-te agradecer mentalmente (ou amaldiçoar-te pela ausência disso).

—

Configurar webhooks entre