Controleer en verwerk inkomende webhooks

Kies de juiste verificatiemethode

De huidige implementatie kent twee leveringsformaten. Ondertekende dashboardgebeurtenissen zijn onder meer Socialjuice-Signature en Socialjuice-Timestamp. Aanvraagformulieren gebruiken in plaats daarvan X-Webhook-Secret. Houd de ondertekening van uw werkruimte alleen geheim op de ontvangende server.

Als er een handtekeningheader aanwezig is, moet u een geldige HMAC-verificatie vereisen. Val niet terug op het accepteren van een ongeldig ondertekend verzoek als een verouderd verzoek. Als u het verzamelingsformaat ondersteunt, moet u de exacte header van het gedeelde geheim vereisen. Ontbrekende authenticatie weigeren.

Een ondertekend verzoek verifiëren

Lees de onbewerkte aanvraagtekst voordat de JSON-middleware deze wijzigt. De handtekening is HMAC SHA-256 van <timestamp>.<raw_request_body> met het handtekeninggeheim. Socialjuice-Signature bevat t=<timestamp>,v1=<hex hmac>. De tijdstempel moet overeenkomen met Socialjuice-Timestamp.

Gebruik een samenvattingsvergelijking met constante tijd. Weiger onjuist opgemaakte headers en tijdstempels die meer dan vijf minuten in het verleden of de toekomst liggen. Houd uw serverklok gesynchroniseerd. Na verificatie parseert u JSON en maakt u onderscheid tussen webhook.test en testimonial.created.

Node.js HMAC-voorbeeld

In dit voorbeeld wordt alleen het ondertekende formaat geverifieerd. Geef het onbewerkte lichaam op als een Buffer voordat JSON wordt geparseerd. Het verifieert de X-Webhook-Secret-inzamelverzoeken niet.

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);
}

Een ophaalverzoek verifiëren

Lees X-Webhook-Secret en vergelijk het met het geconfigureerde ondertekeningsgeheim op uw server. Weiger een lege header of een mismatch. Bewaar het eindpunt op HTTPS en log deze header nooit: de waarde ervan is het geheim zelf.

Dit formaat bevat geen ondertekende tijdstempel of gegarandeerde bezorgings-ID. Het bovenstaande HMAC-voorbeeld kan niet worden gebruikt voor bescherming tegen opnieuw afspelen. Inspecteer het eigenlijke lichaam, zoek de testimonial uuid, indien beschikbaar, en ontdubbel binnen de beoogde werkruimte. Payloads kunnen plat zijn of een genest testimonialobject bevatten.

Accepteer snel en voorkom dubbel werk

Verwerk alleen geverifieerde verzoeken. Voor ondertekende evenementen ontdubbelt u met Socialjuice-Delivery of de envelop-ID. Gebruik voor incassoverzoeken een stabiele testimonial-ID, indien beschikbaar, en behoud de context van de werkruimte. Bewaar deduplicatierecords permanent als verschillende serverinstanties gebeurtenissen ontvangen.

Retourneer onmiddellijk een 2xx-antwoord nadat u een verzoek veilig hebt geaccepteerd en langzamer werk in de wachtrij hebt geplaatst. Beschouw webhook.test als een verbindingstest, niet als een echte testimonial. Als de test is geslaagd, bewijst dit niet dat de toewijzing van de payload van uw collectie correct is.