Configurando webhooks para integrar com seu sistema

O que é um Webhook?

Imagine que a Agnozys é o entregador e seu sistema é a portaria. Em vez de você ligar para a pizzaria a cada 5 minutos perguntando "a pizza tá pronta?" (Polling), a pizzaria manda o motoboy buzinar na sua porta quando estiver pronta (Webhook).

Webhook = A Agnozys avisa seu sistema quando algo acontece.

Eventos Essenciais

Para um SaaS, você precisa escutar pelo menos estes 2 eventos:

1. invoice.paid (Fatura Paga)

• O que fazer: Liberar acesso Premium ao usuário.
• Payload: Recebe o ID do cliente e a data de expiração do plano.
• Ação SQL: UPDATE users SET plan='pro', expires_at='2026-02-05' WHERE id=123;

2. subscription.canceled ou subscription.suspended

• O que fazer: Cortar o acesso.
• Ação SQL: UPDATE users SET plan='free' WHERE id=123;

Como configurar na Agnozys

1. Vá em Desenvolvedores > Webhooks.
2. Clique em + Criar Endpoint.
3. URL: Insira a URL do seu backend (ex: https://api.seusahaan.com/webhooks/agnozys).
4. Eventos: Selecione invoice.paid, subscription.*.
5. Salve.

Segurança (Assinatura HMCA)

Como garantir que quem chamou sua URL foi mesmo a Agnozys e não um hacker tentando liberar acesso grátis?

Nós enviamos um header X-Agnozys-Signature. Você deve pegar o Payload + sua Chave Secreta (que está no painel) e gerar um hash SHA-256. Se bater com o header, é legítimo.

Exemplo em Node.js:

const signature = req.headers['x-agnozys-signature'];
const hash = crypto.createHmac('sha256', secret).update(body).digest('hex');
if (hash !== signature) throw new Error('Invalid signature');

Nunca confie em webhooks sem validar a assinatura.