Bezpieczne testowanie webhooków HubSpot na localhost

Usługa zewnętrzna nie połączy się z localhost. Tunel udostępnia publiczny adres HTTPS i przekazuje prawdziwe nagłówki oraz niezmienione body do lokalnego serwera. Zachowaj surowe body przed parserem JSON. Najpierw sprawdź podpis i dane, trwale zapisz dostawę, a dopiero potem uruchom logikę biznesową.

Jak webhook HubSpot trafia do aplikacji lokalnej

Usługa zewnętrzna nie połączy się z localhost. Tunel udostępnia publiczny adres HTTPS i przekazuje prawdziwe nagłówki oraz niezmienione body do lokalnego serwera. >oficjalna dokumentacja

1. Zbuduj endpoint zachowujący surowe body

Zachowaj surowe body przed parserem JSON. Najpierw sprawdź podpis i dane, trwale zapisz dostawę, a dopiero potem uruchom logikę biznesową.

import express from "express";
import crypto from "node:crypto";

const app = express();
const secret = process.env.HUBSPOT_CLIENT_SECRET;
const publicBase = process.env.WEBHOOK_PUBLIC_BASE_URL;

app.post(
  "/webhooks/hubspot",
  express.raw({ type: "application/json", limit: "1mb" }),
  async (req, res) => {
    const signature = req.get("x-hubspot-signature-v3");
    const timestamp = req.get("x-hubspot-request-timestamp");
    const rawBody = req.body.toString("utf8");

    if (!verifyHubSpotV3({
      signature,
      timestamp,
      method: req.method,
      publicUri: `${publicBase}${req.originalUrl}`,
      rawBody,
      secret,
    })) {
      return res.sendStatus(401);
    }

    let events;
    try {
      events = JSON.parse(rawBody);
      if (!Array.isArray(events)) throw new Error("Expected a batch");
      await enqueueBatchIdempotently(events);
    } catch (error) {
      console.error("HubSpot webhook rejected", error);
      return res.sendStatus(500);
    }

    return res.sendStatus(200);
  }
);

app.use(express.json());
app.listen(3000);

Zapisz pełny adres HTTPS, wybierz tylko potrzebne zdarzenia i wywołaj je na koncie testowym. Sekret przechowuj poza repozytorium.

2. Udostępnij port lokalny przez HTTPS

Uruchom serwer i tunel w drugim terminalu. Odpowiedź 401 na niepodpisany request potwierdza poprawny routing i odrzucenie uwierzytelnienia.

npx portpreview 3000

https://example.portpreview.dev/webhooks/hubspot

Uruchom serwer i tunel w drugim terminalu. Odpowiedź 401 na niepodpisany request potwierdza poprawny routing i odrzucenie uwierzytelnienia.

3. Skonfiguruj webhook w HubSpot

Zapisz pełny adres HTTPS, wybierz tylko potrzebne zdarzenia i wywołaj je na koncie testowym. Sekret przechowuj poza repozytorium. >oficjalna dokumentacja

Obsługuj znane typy, toleruj dodatkowe pola i deduplikuj za pomocą stabilnego identyfikatora dostawy.

Zweryfikuj podpis na dokładnych bajtach

Oblicz HMAC z sekretem webhooka i dokładnymi danymi wskazanymi przez dostawcę. Porównuj w stałym czasie i nie zapisuj sekretu w logach. >oficjalna dokumentacja

function decodeHubSpotQuery(uri) {
  const [base, query] = uri.split("?", 2);
  if (query === undefined) return base;
  const map = {
    "%3A": ":", "%2F": "/", "%3F": "?", "%40": "@",
    "%21": "!", "%24": "$", "%27": "'", "%28": "(",
    "%29": ")", "%2A": "*", "%2C": ",", "%3B": ";",
  };
  const decoded = query.replace(
    /%3A|%2F|%3F|%40|%21|%24|%27|%28|%29|%2A|%2C|%3B/g,
    value => map[value]
  );
  return `${base}?${decoded}`;
}

function verifyHubSpotV3(input) {
  if (!input.secret || !input.signature || !input.timestamp) return false;

  const sentAt = Number(input.timestamp);
  if (!Number.isFinite(sentAt) || Math.abs(Date.now() - sentAt) > 300_000) {
    return false;
  }

  const uri = decodeHubSpotQuery(input.publicUri.split("#")[0]);
  const source = `${input.method}${uri}${input.rawBody}${input.timestamp}`;
  const expected = crypto
    .createHmac("sha256", input.secret)
    .update(source, "utf8")
    .digest("base64");

  const actualBuffer = Buffer.from(input.signature, "utf8");
  const expectedBuffer = Buffer.from(expected, "utf8");
  return actualBuffer.length === expectedBuffer.length &&
    crypto.timingSafeEqual(actualBuffer, expectedBuffer);
}

Po poprawnej weryfikacji podpisu sprawdź znacznik czasu i odrzuć stare wiadomości. Synchronizuj zegar hosta.

Oblicz HMAC z sekretem webhooka i dokładnymi danymi wskazanymi przez dostawcę. Porównuj w stałym czasie i nie zapisuj sekretu w logach. >poradnik

Odpowiadaj szybko i przetwarzaj idempotentnie

Obsługuj znane typy, toleruj dodatkowe pola i deduplikuj za pomocą stabilnego identyfikatora dostawy.

Zarezerwuj identyfikator i utwórz zadanie w jednej transakcji przed odpowiedzią 200. Przy awarii trwałego storage zwróć błąd. >poradnik

Rozwiązywanie problemów z webhookiem HubSpot

• Uruchom serwer i tunel w drugim terminalu. Odpowiedź 401 na niepodpisany request potwierdza poprawny routing i odrzucenie uwierzytelnienia.
• Oblicz HMAC z sekretem webhooka i dokładnymi danymi wskazanymi przez dostawcę. Porównuj w stałym czasie i nie zapisuj sekretu w logach.
• Sprawdź routing, nagłówki, podpis, czas odpowiedzi i idempotencję. Syntetyczne requesty najlepiej nadają się do testowania odrzuceń.
• Sprawdź ścieżkę POST, port tunelu, surowe body, sekret, zegar i opóźnienia bazy danych.

>poradnik · >poradnik

Lista zabezpieczeń dla środowiska lokalnego i produkcji

• Wymagaj HTTPS, ogranicz rozmiar i metodę, chroń sekrety, maskuj dane w logach i usuwaj nieaktualne adresy testowe.
• Zachowaj surowe body przed parserem JSON. Najpierw sprawdź podpis i dane, trwale zapisz dostawę, a dopiero potem uruchom logikę biznesową.
• Zarezerwuj identyfikator i utwórz zadanie w jednej transakcji przed odpowiedzią 200. Przy awarii trwałego storage zwróć błąd.

Wymagaj HTTPS, ogranicz rozmiar i metodę, chroń sekrety, maskuj dane w logach i usuwaj nieaktualne adresy testowe.