Entrega e assinatura

O proprietário configura destinos em Configurações → Desenvolvedor. Escolha um endereço HTTPS público e os tipos de evento desejados. Eventos são gerados por mudanças feitas no painel, na API e nos callbacks de processamento. data.object contém o objeto público completo; data.previous_attributes contém os valores anteriores dos campos alterados. request.id identifica a chamada de origem quando disponível e pode ser null. Consulte Escolher eventos, o catálogo de tipos e o objeto do evento.

Verificar a assinatura

Cada entrega envia Hubfy-Event-Id e Hubfy-Signature. A assinatura tem o formato t=TIMESTAMP,v1=HEX e usa HMAC-SHA256 sobre TIMESTAMP + "." + CORPO_ORIGINAL, com o segredo do destino. Leia os bytes originais antes de interpretar o JSON. Verifique a assinatura em tempo constante e limite a diferença de horário, por exemplo a cinco minutos. O servidor deve manter seu relógio sincronizado.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWebhook(rawBody, signature, secret) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(signature ?? '');
  if (!match || Math.abs(Date.now() / 1000 - Number(match[1])) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(match[1] + '.').update(rawBody).digest();
  const received = Buffer.from(match[2], 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Confirmar e deduplicar

Persista o evento ou o trabalho que ele inicia e responda rapidamente com 2xx. Use o ID do evento para evitar executar a mesma ação duas vezes. Entregas podem se repetir e não têm garantia de ordem; consulte o recurso quando precisar do estado atual.

Novas tentativas

Sem resposta 2xx, a Hubfy agenda outra tentativa. São até oito tentativas por ciclo, com intervalos de 1 minuto, 5 minutos, 30 minutos, 2 horas, 8 horas, 24 horas e 24 horas. O agendamento pode acrescentar atraso. O timeout por tentativa é de 10 segundos. Redirecionamentos não são seguidos. No painel, confira status, tentativas e código HTTP. Corrija o destino e use o reenvio manual quando necessário; ele permite outro ciclo de até oito tentativas e preserva o histórico. Ao rotacionar o segredo, atualize a verificação no destino. As entregas seguintes usam o segredo atual. Para pausar uma integração, desative o destino; o histórico permanece disponível.

Fundamentos da API

Objetos

Webhooks e eventos

Entrega e assinatura

Verificar a assinatura

Confirmar e deduplicar

Novas tentativas

​Verificar a assinatura

​Confirmar e deduplicar

​Novas tentativas

Verificar a assinatura

Confirmar e deduplicar

Novas tentativas