Testowanie Supabase Database Webhooks na localhost

Aby przetestować PPXTERM001XPP Database Webhook na localhost, należy użyć host.docker.internal gdy zarówno PPXTERM002XPP jak i odbiornik uruchamiają się na Twojej maszynie lub korzystają z publicznego tunelu HTTPS, gdy prowadzony projekt Supabase musi zadzwonić do lokalnej aplikacji. Rozróżnienie ma znaczenie: lokalne PPXTERM005XPP działa w PPXTERM006XPP, gdzie localhost oznacza kontener bazy danych, podczas gdy hostowany Supabase potrzebuje dostępnego w sieci adresu URL.

Co wysyła PPXTERM009XPP Database Webhooks

Database Webhooks reaguje na Postgres INSERT, UPDATEoraz DELETE operacje na wybranej tabeli. Supabase opisuje je jako asynchroniczne opakowanie wokół wyzwalaczy za pomocą pg_net rozszerzenie. Transakcja, która zmienia wiersz nie czeka, aż odbiornik zakończy swoją logikę biznesową, co zmniejsza sprzęganie, ale także oznacza, że odbiornik musi być obserwowalny i świadomy awarii.

JSON identyfikuje działanie, schemat i tabelę oraz zawiera dane wierszy. Do wkładek i aktualizacji, record zawiera nowy wiersz. Dla aktualizacji i usunięcia, old_record podaje poprzedni wiersz, jeżeli jest dostępny. Zbuduj opiekunów wokół udokumentowanej koperty zamiast traktować każde żądanie jako tylko obiekt wierszy.

Local stock versus host project

Lokalna aplikacja Supabase: użyj hosta Docker

Kiedy uciekasz supabase start, Postgres jest wewnątrz pojemnika. URL z hakiem WWW, jak np. http://localhost:3000/api/supabase-db-hook Zapętla się z powrotem do tego pojemnika i zazwyczaj zawodzi. Supabase Dokumentacja Database Webhooks mówi do celu host.docker.internal:

http://host.docker.internal:3000/api/supabase-db-hook

Ta trasa nie wymaga publicznego tunelu. Na silnikach Linux, w których ta nazwa hosta jest niedostępna, użyj mapowania bramki obsługiwanego przez konfigurację Docker lub adres LAN maszyny, jak sugerują dokumenty Supabase. Potwierdź z pojemnika, nie tylko z przeglądarki hosta.

Supabase do aplikacji lokalnej: HTTPS

Baza danych w chmurze nie może rozwiązać nazwy komputera Docker lub prywatnego adresu Loopback. Uruchom aplikację lokalną i uruchom npx portpreview 3000, następnie skonfigurować:

https://your-subdomain.portpreview.dev/api/supabase-db-hook

Użyj dedykowanego projektu rozwojowego lub tabeli niskiego ryzyka. Chmura webhook może zawierać prawdziwe dane wiersza, więc wystawienie tabeli produkcyjnej do tymczasowego URL rozwoju jest zazwyczaj kiepską strategią testową.

Utwórz odbiornik, który potwierdzi wspólny sekret

W przeciwieństwie do dostawców, którzy definiują obowiązkowy nagłówek HMAC, Database Webhook jest konfigurowalnym wychodzącym żądaniem HTTP. Chronić punkt końcowy sekretnym nagłówkiem, który kontrolujesz i skonfigurować ten sam nagłówek na haku. TLS chroni go w tranzycie; porównanie czasu stałego pozwala uniknąć wycieku czasu secret- prefix przez aplikację.

// app/api/supabase-db-hook/route.ts
import crypto from 'node:crypto';

function safeEqual(a: string, b: string) {
  const left = Buffer.from(a);
  const right = Buffer.from(b);
  return left.length === right.length &&
    crypto.timingSafeEqual(left, right);
}

export async function POST(request: Request) {
  const supplied = request.headers.get('x-webhook-secret') ?? '';
  const expected = process.env.SUPABASE_DB_WEBHOOK_SECRET ?? '';

  if (!expected || !safeEqual(supplied, expected)) {
    return new Response('unauthorized', { status: 401 });
  }

  const payload = await request.json();
  if (!['INSERT', 'UPDATE', 'DELETE'].includes(payload.type)) {
    return new Response('unsupported event', { status: 400 });
  }

  await recordDelivery(payload);
  return new Response('accepted', { status: 200 });
}

Wspólny nagłówek potwierdza znajomość tajemnicy, ale nie kryptograficznie wiąże ją z ciałem. Jeśli wymagane są dowody manipulacji na poziomie nadwozia, należy wysłać Database Webhook do małego zaufanego Edge Function, który waliduje swój własny sekret przychodzący, oblicza wybrany HMAC nad kanonicznym organem wychodzącym, a następnie przekazuje go do lokalnego lub produkcyjnego konsumenta. Nie wymyślaj X-Supabase-Signature Założenia, chyba że własna warstwa spedycyjna tworzy i weryfikuje je.

Konfiguracja i uruchamianie fokusa

1. Wybierz tabelę rozwoju i zdecydować, które operacje mają znaczenie.
2. Utwórz Database Webhook w płycie rozdzielczej Supabase w bazie danych → Haki internetowe, wybierając schemat, tabelę i operacje.
3. Ustaw lokalny adres URL Docker lub publiczny adres URL tunelu opisany powyżej.
4. Dodaj Content-Type: application/json i losowy X-Webhook-Secret wartość, w której dostępna jest konfiguracja nagłówka haka.
5. Uruchom odbiornik i wstaw wyraźnie oznaczony wiersz testowy.
6. Uaktualnij jedno pole, a następnie usuń wiersz, weryfikując wszystkie wybrane koperty.
7. Przed zmianą projektu lub zamknięciem tunelu należy usunąć lub wyłączyć haczyk.

Nazwa wierszy testowych, więc czyszczenie jest determinujące. Nie odpalaj całodobowej integracji w rejestrach klientów produkcyjnych tylko po to, aby zobaczyć wniosek o przybycie.

Interpret INSERT, UPDATE i DELETE bezpiecznie

INSERT

Stosowanie record jako nowo wprowadzony stan. Jeśli odbiornik tworzy odpowiedni obiekt gdzie indziej, należy przechowywać klucz podstawowy tabeli źródłowej jako klucz idepotencji. Event insert może być ponownie dostarczony podczas ręcznej powtórki lub niestandardowego powtórnego przetwarzania.

UPDATE

Porównaj record z old_record i działają wyłącznie w dziedzinach istotnych dla integracji. Ogólny hak webhook może wystrzelić dla znaczników czasu lub niepowiązanych metadanych. Filtrowanie nieoperacyjnych zmian biznesowych zapobiega kosztownym połączeniom niższego szczebla.

DELETE

Usunięty wiersz jest reprezentowany przez poprzednie dane zamiast bieżącego rekordu. Unieszkodliwianie osób zajmujących się usuwaniem brakujących opcjonalnych pól i decydowanie o tym, czy działanie niższego szczebla jest usuwaniem, archiwalnym czy cofnięciem. Wymogi dotyczące audytu zachowawczego.

switch (payload.type) {
  case 'INSERT':
    await mirror.upsert(payload.record.id, payload.record);
    break;
  case 'UPDATE':
    if (payload.old_record.status !== payload.record.status) {
      await syncStatus(payload.record.id, payload.record.status);
    }
    break;
  case 'DELETE':
    await mirror.archive(payload.old_record.id);
    break;
}

Niezawodność dostawy jest problemem aplikacji

Ponieważ Database Webhooks są asynchroniczne żądania sieciowe, nie traktuj paragonu jako transakcji rozproszonej ze zmianą wiersza. Zdalna strona może być niedostępna po wypowiedziach Postgres. Monitoruj wyniki wniosków i projektowanie dla wszystkiego, co nie może zostać utracone.

Dla wysokowartościowych przepływów pracy, tablica wygrywająca jest mocniejsza: napisz zmianę biznesową i wyślij wiersz w jednej transakcji bazy danych, a następnie pozwól pracownikowi dostarczyć z wyraźnymi licznikami powtórzeń, backoff i dead- letter obsługi. Database Webhook może powiadomić pracownika, ale okresowe pojednanie powinno nadal znaleźć niedostarczone wiersze skrzynki odbiorczej.

Zrób z odbiornika idempotenta. Przydatny klucz łączy schemat źródłowy, tabelę, działanie, klucz podstawowy i stabilną wersję wiersza, taką jak: updated_at; dla ścisłych gwarancji, dodać niezmienne zdarzenie UUID w wierszu wypisowym. Unikaj hakowania tylko bieżącego wiersza, ponieważ dwa ważne przejścia mogą tworzyć podobne projekcje.

Połączenie lokalnego Supabase Edge Function

Jeśli celem jest Edge Function obsługiwany przez lokalny stos Supabase, udokumentowany przykład to:

http://host.docker.internal:54321/functions/v1/my-function-name

Urzędnik Edge Functions przewodnik rozwoju zastosowania supabase functions serve [function-name] do lokalnego przeładowania. Edge Functions domyślnie wymaga weryfikacji JWT. Dla funkcji webhook, która nie może dostarczyć użytkownikowi JWT, skonfigurować tę funkcję celowo, na przykład z verify_jwt = false w supabase/config.toml, udokumentowane w Konfiguracja funkcji. Zastąpić uwierzytelnianie JWT za pomocą nagłówek lub kontroli podpisu; wyłączenie JWT tylko czyni funkcję publiczną.

Troubleshoot Supabase webhook localhost dostawy

Połączenie odmówione z lokalnego stosu

Zastąp localhost z host.docker.internal, sprawdzić, czy aplikacja wiąże się z interfejsem osiągalnym z Docker i potwierdzić port. Na Linux skonfiguruj rozdzielczość bramki host- lub użyj IP hosta. Usługa związana tylko z nieoczekiwanym interfejsem może nadal odrzucać ruch kontenera.

Projekt gospodarza nigdy nie dociera do trasy

Gościnny projekt wymaga publicznego URL tunelu HTTPS, a nie nazwy komputera Docker. Potwierdź, że tunel jest na żywo, a jego adres URL zawiera pełną trasę. Sprawdź DNS / TLS, wysyłając do niego samemu.

Trasa powraca 401

Porównaj skonfigurowaną nazwę nagłówka i wartość, obserwuj prowadzenie lub śledzenie Whitespace i ponownie uruchom aplikację po zmianie zmiennych środowiskowych. Zaloguj, czy nagłówek istnieje, nigdy jego wartość. Jeżeli pośredniczący pakuje niestandardowe nagłówki, należy użyć konwencjonalnego Authorization: Bearer ... nagłówek i potwierdzić go wyraźnie.

Kształt ładunku wydaje się zły

Zaloguj tylko klucze najwyższego poziomu, działanie, schemat i tabelę w rozwoju. Pamiętaj, że DELETE wykorzystuje poprzednie dane wiersza, a UPDATE może zawierać obie wersje. Sprawdzić przed zmianą parsera.

Aktualizacja bazy danych jest skuteczna, ale brakuje dalszych prac

To zachowanie jest możliwe w asynchronicznym projekcie. Sprawdź dzienniki zapytań haka WWW oraz pg_net diagnostyka dostępna w Twoim środowisku, a następnie dodać ponownie lub pojednanie, zamiast wycofywać już zaangażowaną transakcję biznesową.

Lista kontrolna bezpieczeństwa

• Użyj HTTPS do testów hosted-to-local i obróć tymczasowy wspólny sekret później.
• Wysyłanie tylko niezbędnych kolumn; unikaj ujawniania wrażliwych tabel lub szerokich obciążeń produkcyjnych.
• Sprawdzić tajny nagłówek przed parsowaniem lub uporczywością ciała.
• Zastosuj tylko routing POST-, limity wielkości zapotrzebowania, kontrole stawek i zredagowane dzienniki.
• Użyj osobnych lokalnych, inscenizacyjnych i produkcyjnych konfiguracji haka.
• Zbuduj wyraźne powtórzenia, impotencję, monitorowanie i pojednanie dla ważnych wydarzeń.
• Wyłącz tymczasowe adresy URL w chmurze po zamknięciu tunelu.

Najczęstszym lokalnym błędem jest adresowanie sieciowe, a nie Postgres: wywołania local- kontener host.docker.internal; rozmowy w chmurze korzystają z publicznego tunelu. Po przybyciu ruchu, traktować uwierzytelnianie i gwarancji dostawy jako oddzielne problemy konstrukcyjne. Przegląd lokalna ochrona tunelu hosta oraz Wzory niezawodności haka przed połączeniem danych wrażliwych.