SDK

Punkty końcowe

`webhooks.list`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test` i `listDeliveries`.

Wszystkie metody

usage.ts

const endpoint = await openemail.webhooks.create({  url: 'https://acme.com/hooks/mail',  eventTypes: ['email.sent', 'email.bounced'],  description: 'Billing service',}) await store(endpoint.secret) await openemail.webhooks.list()await openemail.webhooks.get(endpoint.id)await openemail.webhooks.update(endpoint.id, { enabled: false })await openemail.webhooks.test(endpoint.id)const rotated = await openemail.webhooks.rotateSecret(endpoint.id)await openemail.webhooks.delete(endpoint.id)

create to JEDYNY moment, w którym zwracany jest sekret — poza rotateSecret. Odczyt nigdy go nie powtarza, więc zapisz go, zanim zrobisz cokolwiek innego. Pomiń eventTypes, aby otrzymywać każde zdarzenie, łącznie z tymi dodanymi później.

rotateSecret nie ma okna nakładania się. Stary sekret przestaje działać natychmiast, więc wdróż nowy, zanim wykonasz rotację. Wywołanie to nigdy nie jest ponawiane automatycznie: ponowienie wykonałoby rotację drugi raz i unieważniło sekret zwrócony przez pierwszą próbę.

Co można subskrybować

WEBHOOK_EVENTS jest eksportowane, żebyś mógł wyrenderować tę listę. Zdarzenia są zdarzeniami **skrzynki**, a nie tego API: email.received odpala się dla poczty, która przychodzi do aplikacji, a email.sent dla wiadomości wysłanej z okna tworzenia. Subskrypcja to nie to samo co podglądanie własnego ruchu w API.

Dowód, że działa

webhook-test.ts

const result = await openemail.webhooks.test('whe_…')console.log(result.delivery?.status, result.delivery?.responseCode) const deliveries = await openemail.webhooks.listDeliveries('whe_…')for (const d of deliveries) console.log(d.eventType, d.status, d.responseCode, d.error)

responseCode równe null oznacza, że odpowiedzi nie było w ogóle (DNS, TLS, timeout), co jest innym faktem niż odpowiedź mówiąca 0. Każdy wiersz niesie attempt i maxAttempts, więc kilka wierszy może opisywać jedno zdarzenie: to samo payload.id w nich wszystkich to zdarzenie, a numer próby to próba.

Parametry: webhooks.create

urlstringwymagane: Dokąd wysyłane są dostarczenia metodą POST. Tylko HTTPS, a host nie może być `localhost`, nazwą `.localhost`/`.local`/`.internal` ani literałem IP z zakresu loopback, prywatnego, CGNAT czy link-local. To pobranie po stronie serwera pod adres, który podajesz, więc takie przypadki dają 422 na `url`; kontrola czyta nazwę hosta tak, jak ją zapisano, i nigdy nie rozwiązuje DNS. Zapisywana jest serializacja parsera URL z tego, co wysłano, więc `https://acme.com` odczytuje się z powrotem jako `https://acme.com/`.
eventTypesWebhookEvent[]: Które zdarzenia docierają do tego endpointu: dowolne nazwy z `WEBHOOK_EVENTS`. `POST /webhooks` ogranicza tablicę do liczby istniejących zdarzeń, więc jedno więcej daje 422 na `eventTypes`; `PATCH` jej nie ogranicza. Ograniczana jest wyłącznie długość, a powtórzona nazwa jest zapisywana i odczytywana dokładnie tak, jak ją wysłano. Pominięcie lub pusta wartość zapisywane są jako pusta lista — dlatego odczytuje się ją jako `['*']` — i oznacza to każde zdarzenie `email.*` poza `email.replied`, dziś czternaście, i nigdy rodziny zdarzeń domenowych ani wykluczeń. Rodzina dodana później nigdy nie dotrze do endpointu, który jej nie wymienił, więc integracja nie zacznie odbierać nieznanego sobie kształtu z powodu nowego wydania.
descriptionstring: Etykieta endpointu, najwyżej 200 znaków, dzięki czemu lista webhooków czyta się jako nazwy, a nie kolumna URL-i. Przy pominięciu zapisywana i zwracana jest jako null.

Odpowiedź: CreatedWebhookResource

object'webhook': Zawsze `'webhook'` — ten sam dyskryminator, który zwraca zwykły odczyt, bo sekret jest jednym dodatkowym kluczem na zwyczajnym kształcie, a nie osobnym typem obiektu. O tym, czy `secret` jest obecny, decyduje to, którą metodę wywołano, a nie to pole.
idstring: Identyfikator endpointu: `whe_` i 24 znaki szesnastkowe. Przyjmuje go każde inne wywołanie webhooków: `get`, `update`, `delete`, `rotateSecret`, `test` i `listDeliveries`.
urlstring: Endpoint w postaci zapisanej, po przejściu kontroli HTTPS i zablokowanych hostów. To sparsowany URL zserializowany ponownie, więc porównuj z tą wartością, a nie z ciągiem, który wysłałeś.
descriptionstring | null: Etykieta, którą mu nadałeś, albo null, jeśli żadnej nie podałeś. `update` wysyłający jawne null czyści ją z powrotem do null.
eventTypesWebhookEvent[] | ['*']: Zasubskrybowane zdarzenia albo `['*']`, gdy endpoint nie wymienił żadnego. `['*']` to sposób renderowania pustej zapisanej listy przy odczycie i nie można go odesłać z powrotem; oznacza trzynaście zdarzeń wiadomości, a nie cały katalog. `create` i `update` przyjmują wyłącznie dosłowne nazwy zdarzeń.
enabledboolean: Czy podejmowane są próby dostarczenia; wyłączony endpoint jest pomijany przy rozsyłaniu zdarzeń i zachowuje swój sekret oraz historię dostarczeń. Tutaj zawsze true, bo `WebhookCreate` nie ma pola `enabled` — ma je tylko `WebhookPatch`.
lastDeliveryAtstring | null: Znacznik czasu ISO 8601 ostatniej PRÓBY dostarczenia, a nie ostatniego sukcesu. Jest stemplowany również po nieudanym POST, więc mówi ci, że endpoint został wypróbowany, a `listDeliveries` mówi, jak poszło. Null do pierwszej próby, a więc zawsze null przy `create`.
createdAtstring: Znacznik czasu ISO 8601 rejestracji endpointu. `list` zwraca endpointy posortowane po tym polu, od najnowszych.
secretstring: Klucz HMAC-SHA-256, którym podpisywany jest nagłówek `X-OpenEmail-Signature` każdej dostawy: `whsec_`, a po nim 32 losowe bajty w base64url — i to jego przekazujesz do `verifyWebhookSignature`. Zwracają go wyłącznie `create` oraz `rotateSecret` i nic poza nimi. Odczyt nigdy go nie powtarza, więc zapisz go od razu; utracony sekret można jedynie zastąpić przez `rotateSecret`, co natychmiast unieważnia poprzedni.