Guia de webhooks

1. Crie um ponto final de webhook

Primeiro, crie um endpoint HTTP em seu aplicativo que possa receber solicitações POST do LicenseChain.

// Express.js Example
app.post('/webhooks/licensechain', async (req, res) => {'{'}
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const payload = JSON.stringify(req.body);
  
  // Verify signature (see Security section)
  if (!verifySignature(payload, signature, timestamp, webhookSecret)) {'{'}
    return res.status(401).send('Invalid signature');
  {'}'}
  
  // Process webhook event
  const event = req.body;
  console.log('Received event:', event.type, event.data);
  
  res.status(200).send('OK');
{'}'});

2. Registre seu webhook

Use a API LicenseChain para registrar seu endpoint de webhook. Você precisará fornecer o URL e especificar quais eventos deseja receber.

POST /v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{'{'}
  "url": "https://your-app.com/webhooks/licensechain",
  "events": ["license.created", "license.updated", "license.revoked"],
  "secret": "optional-custom-secret"
{'}'}

3. Eventos disponíveis

LicenseChain oferece suporte aos seguintes eventos de webhook:

Assinaturas de webhook

Todas as solicitações de webhook incluem uma assinatura no X-Webhook-Signature cabeçalho. A assinatura é HMAC-SHA256 do corpo da solicitação bruta usando seu segredo do webhook. Sempre verifique usando comparação em tempo constante (por exemplo crypto.timingSafeEqual) para evitar ataques de temporização. O valor do cabeçalho pode ser hexadecimal bruto ou sha256= seguido por hexadecimal; despir o sha256= prefixo antes de comparar buffers hexadecimais para que os comprimentos correspondam.

// Node.js Example (constant-time, supports sha256= prefix)
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {'{'}
  if (!payload || !signature || !secret) return false;
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  const received = String(signature).startsWith('sha256=') ? String(signature).slice(7) : String(signature);
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(received, 'hex');
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
{'}'}

// In your webhook handler (use raw body for payload)
const signature = req.headers['x-webhook-signature'];
const payload = req.rawBody || JSON.stringify(req.body);
if (!verifySignature(payload, signature, webhookSecret)) {'{'}
  return res.status(401).send('Invalid signature');
{'}'}

Solicitar cabeçalhos

LicenseChain inclui os seguintes cabeçalhos com cada solicitação de webhook:

Listar todos os webhooks

GET /v1/webhooks?page=1&limit=10
Authorization: Bearer YOUR_API_KEY

Obtenha detalhes do webhook

GET /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY

Atualizar webhook

PUT /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{'{'}
  "url": "https://new-url.com/webhooks",
  "events": ["license.created", "license.updated"]
{'}'}

Excluir webhook

DELETE /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY

Enviar webhook de teste

Você pode testar seu endpoint de webhook sem esperar que um evento real ocorra:

POST /v1/webhooks/:id/test
Authorization: Bearer YOUR_API_KEY

Isso enviará um evento de teste para o URL do seu webhook com uma carga útil de amostra. Use isso para verificar se seu endpoint está funcionando corretamente.

Ver registros de webhook

Verifique o status de entrega e a resposta para cada evento de webhook:

GET /v1/webhooks/:id/logs?page=1&limit=10
Authorization: Bearer YOUR_API_KEY

Os logs incluem o código de status HTTP, o corpo da resposta e se a entrega foi bem-sucedida.

✅ Sempre verifique as assinaturas

Nunca processe eventos de webhook sem verificar a assinatura. Isso garante que a solicitação seja do LicenseChain e não tenha sido adulterada.

✅ Responda rapidamente

Seu endpoint do webhook deve responder em 5 segundos. Para operações de longa duração, reconheça o webhook imediatamente e processe de forma assíncrona.

✅ Lidar com idempotência

Use o ID do evento para evitar o processamento do mesmo evento várias vezes. Armazene IDs de eventos processados ​​e verifique antes do processamento.

✅ Utilize HTTPS

Sempre use HTTPS para seus endpoints de webhook para garantir que os dados sejam criptografados em trânsito.

✅ Monitore registros de webhook

Verifique regularmente os logs do webhook para identificar e corrigir problemas de entrega. Configure alertas para entregas com falha.

Webhook não está recebendo eventos

• • Verifique se o URL do seu webhook pode ser acessado pela Internet
• • Verifique se o seu endpoint retorna um código de status 2xx
• • Certifique-se de que os eventos que você assinou estão realmente ocorrendo
• • Revise os registros do webhook em busca de erros de entrega

Falha na verificação de assinatura

• • Verifique se você está usando o segredo do webhook correto
• • Verifique se você está assinando o corpo exato da solicitação (como string JSON)
• • Verifique se você está usando o algoritmo HMAC-SHA256
• • Certifique-se de que os cabeçalhos estejam sendo lidos corretamente (diferencia maiúsculas de minúsculas)

Erros de tempo limite

• • Otimize seu gerenciador de webhook para responder rapidamente
• • Mova o processamento pesado para trabalhos em segundo plano
• • Retorne 200 OK imediatamente e processe de forma assíncrona