Verifica e gestisci i webhook in entrata

Scegli il metodo di verifica corretto

L'implementazione attuale prevede due formati di consegna. Gli eventi del dashboard firmati includono Socialjuice-Signature e Socialjuice-Timestamp. Le richieste del modulo di raccolta utilizzano invece X-Webhook-Secret. Mantieni segreta la firma del tuo spazio solo sul server ricevente.

Se è presente un'intestazione della firma, richiede una verifica HMAC valida. Non ricorrere all'accettazione di una richiesta firmata non valida come richiesta legacy. Se supporti il ​​formato di raccolta, richiedi l'esatta intestazione shared-secret. Rifiuta l'autenticazione mancante.

Verifica una richiesta firmata

Leggere il corpo della richiesta non elaborata prima che il middleware JSON lo modifichi. La firma è HMAC SHA-256 di <timestamp>.<raw_request_body> con il segreto della firma. Socialjuice-Signature contiene t=<timestamp>,v1=<hex hmac>. Il suo timestamp deve concordare con Socialjuice-Timestamp.

Utilizzare un confronto digest a tempo costante. Rifiuta intestazioni e timestamp non corretti con più di cinque minuti nel passato o nel futuro. Mantieni sincronizzato l'orologio del tuo server. Dopo la verifica, analizzare JSON e distinguere webhook.test da testimonial.created.

Esempio HMAC di Node.js

Questo esempio verifica solo il formato firmato. Fornire il corpo grezzo come Buffer prima dell'analisi JSON. Non autentica le richieste di raccolta X-Webhook-Secret.

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

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

Verificare una richiesta di ritiro

Leggi X-Webhook-Secret e confrontalo con il segreto di firma configurato sul tuo server. Rifiuta un'intestazione vuota o una mancata corrispondenza. Mantieni l'endpoint su HTTPS e non registrare mai questa intestazione: il suo valore è il segreto stesso.

Questo formato non include un timestamp firmato o un ID di consegna garantito. Non è possibile utilizzare l'esempio HMAC riportato sopra per la protezione dalla riproduzione. Ispeziona il corpo reale, trova la testimonianza uuid ove disponibile e deduplica nello spazio previsto. I payload possono essere piatti o contenere un oggetto testimonianza nidificato.

Accetta rapidamente ed evita lavori duplicati

Elabora solo le richieste autenticate. Per gli eventi firmati, deduplicare con Socialjuice-Delivery o l'ID busta. Per le richieste di ritiro, utilizza un identificatore di testimonianza stabile quando disponibile e mantieni il contesto dell'area di lavoro. Archivia i record di deduplicazione in modo persistente se diverse istanze del server ricevono eventi.

Restituisci una risposta 2xx tempestivamente dopo aver accettato in sicurezza una richiesta e accoda il lavoro più lento. Tratta webhook.test come un test di connessione, non come una vera testimonianza. Il superamento del test non dimostra che la mappatura del carico utile della raccolta sia corretta.