Endpointy
`webhooks.list`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test` a `listDeliveries`.
Všechny metody
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 je JEDINÁ chvíle, kdy se tajný klíč vrací, kromě rotateSecret. Čtení jej nikdy nezopakuje, takže si ho uložte dřív, než uděláte cokoli jiného. Vynechte eventTypes, chcete-li dostávat každou událost, i ty pozdější.
rotateSecret nemá žádné překryvné okno. Starý tajný klíč okamžitě přestane fungovat, takže nový nasaďte dřív, než budete rotovat. Automaticky se nikdy neopakuje: opakování by rotovalo podruhé a zneplatnilo tajný klíč, který vrátil první pokus.
K čemu se můžete přihlásit
WEBHOOK_EVENTS je exportován, abyste mohli seznam vykreslit. Události jsou událostmi **schránky**, ne tohoto API: email.received se spouští pro poštu, která dorazí do aplikace, a email.sent pro zprávu, kterou odeslal editor. Přihlásit se k odběru není totéž jako sledovat vlastní provoz na API.
Jak ověřit, že to funguje
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 s hodnotou null znamená, že žádná odpověď nepřišla vůbec (DNS, TLS, timeout), což je jiný fakt než odpověď, která řekla 0. Každý řádek nese attempt a maxAttempts, takže jednu událost může popisovat několik řádků: stejné payload.id napříč nimi je ta událost a číslo pokusu je pokus.
Parametry: webhooks.create
urlstringpovinné- Kam se doručení POSTují. Jen HTTPS a hostitel nesmí být `localhost`, název `.localhost`/`.local`/`.internal` ani IP literál typu loopback, privátní, CGNAT či link-local. Jde o server-side fetch na adresu, kterou dodáte, takže takové hodnoty jsou 422 na `url`; kontrola čte název hostitele tak, jak je napsaný, a nikdy neresolvuje DNS. Ukládá se serializace toho, co jste poslali, tak jak ji vrátí parser URL, takže `https://acme.com` se čte zpět jako `https://acme.com/`.
eventTypesWebhookEvent[]- Které události se na tento endpoint dostanou: kterýkoli z názvů ve `WEBHOOK_EVENTS`. `POST /webhooks` omezuje pole počtem existujících událostí, takže o jednu víc je 422 na `eventTypes`; `PATCH` je neomezuje. Omezena je jen délka a opakovaný název se uloží i přečte zpět přesně tak, jak jste ho poslali. Vynechaná nebo prázdná hodnota se uloží jako prázdný seznam, proto se zpět čte jako `['*']`, a znamená každou událost `email.*` kromě `email.replied`, dnes jich je čtrnáct, a nikdy ne rodiny domén či potlačení. Rodina přidaná později se nikdy nedostane na endpoint, který ji nejmenoval, takže integrace nemůže kvůli nějakému vydání začít dostávat tvar, který nikdy neviděla.
descriptionstring- Popiska endpointu, nejvýše 200 znaků, aby se seznam webhooků četl jako názvy, a ne jako sloupec URL. Když se vynechá, uloží se i vrací jako null.
Odpověď: CreatedWebhookResource
object'webhook'- Vždy `'webhook'`, tentýž diskriminátor, jaký vrací běžné čtení, protože tajný klíč je jen jeden klíč navíc v obvyklém tvaru, ne samostatný typ objektu. O tom, zda je `secret` přítomen, rozhoduje metoda, kterou jste zavolali, ne toto pole.
idstring- Identifikátor endpointu: `whe_` následované 24 hexadecimálními znaky. Bere ho každé další volání webhooků: `get`, `update`, `delete`, `rotateSecret`, `test` a `listDeliveries`.
urlstring- Endpoint tak, jak je uložen, po projití kontrolami HTTPS a blokovaných hostitelů. Je to znovu serializovaná naparsovaná URL, takže porovnávejte proti této hodnotě, ne proti řetězci, který jste poslali.
descriptionstring | null- Popiska, kterou jste mu dali, nebo null, pokud jste žádnou nedali. `update`, který pošle explicitní null, ji vrátí zpět na null.
eventTypesWebhookEvent[] | ['*']- Odebírané události, nebo `['*']`, když endpoint žádné nejmenoval. `['*']` je způsob, jakým se při čtení vykresluje prázdný uložený seznam, nelze ho poslat zpět a zastupuje třináct událostí zpráv, ne celý katalog. `create` a `update` přijímají jen doslovné názvy událostí.
enabledboolean- Zda se doručení pokoušejí; zakázaný endpoint se při rozesílání událostí přeskakuje a ponechává si tajný klíč i historii doručení. Tady vždy true, protože `WebhookCreate` žádné `enabled` nemá, má ho jen `WebhookPatch`.
lastDeliveryAtstring | null- Časové razítko ISO 8601 posledního POKUSU o doručení, ne posledního úspěchu. Razítkuje se i po neúspěšném POST, takže vám říká, že se endpoint zkusil, a `listDeliveries` vám řekne, jak to dopadlo. Než přijde první pokus, je null, a tedy vždy null u `create`.
createdAtstring- Časové razítko ISO 8601 toho, kdy byl endpoint zaregistrován. `list` podle tohoto pole vrací endpointy od nejnovějších.
secretstring- Klíč HMAC-SHA-256, kterým se podepisuje hlavička `X-OpenEmail-Signature` u každého doručení: `whsec_` následovaný 32 náhodnými bajty v base64url, tedy přesně to, co předáváte funkci `verifyWebhookSignature`. Vracejí jej jen `create` a `rotateSecret`, nic jiného. Čtení jej nikdy nezopakuje, takže si jej uložte hned; ztracený tajný klíč lze pouze nahradit pomocí `rotateSecret`, což ten původní okamžitě zneplatní.