Végpontok
`webhooks.list`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test` és `listDeliveries`.
Minden metódus
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)A create az EGYETLEN alkalom, amikor a titok visszajön, a rotateSecret mellett. Olvasás soha nem adja vissza, ezért mindenek előtt tárold el. Hagyd el az eventTypes mezőt, ha minden eseményt meg akarsz kapni, a későbbieket is beleértve.
A rotateSecret hívásnak nincs átfedési ablaka. A régi titok azonnal érvényét veszti, ezért az újat a rotálás előtt vezesd be. Automatikusan soha nem kerül újrapróbálásra: az újrapróbálkozás másodszor is rotálna, és érvénytelenítené azt a titkot, amelyet az első próbálkozás visszaadott.
Mire iratkozhatsz fel
A WEBHOOK_EVENTS exportálva van, hogy meg tudd jeleníteni a listát. Az események a **postafiók** eseményei, nem ezé az API-é: az email.received az alkalmazásba érkező levélre sül el, az email.sent pedig a szerkesztőből elküldött üzenetre. A feliratkozás nem ugyanaz, mint a saját API-forgalmad figyelése.
Annak bizonyítása, hogy működik
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)A null értékű responseCode azt jelenti, hogy egyáltalán nem volt válasz (DNS, TLS, időtúllépés), ami más tény, mint egy 0-t mondó válasz. Minden sor hordozza az attempt és a maxAttempts értéket, így több sor is leírhat egyetlen eseményt: a közös payload.id az esemény, a próbálkozás száma pedig a kísérlet.
Paraméterek: webhooks.create
urlstringkötelező- Ide POST-olja a rendszer a kézbesítéseket. Csak HTTPS, és a hoszt nem lehet `localhost`, `.localhost`/`.local`/`.internal` név, sem loopback, privát, CGNAT vagy link-local IP-literál. Ez szerveroldali fetch egy általad megadott címre, ezért ezek 422-t kapnak az `url` mezőn; az ellenőrzés a hosztnevet úgy olvassa, ahogy le van írva, és soha nem old fel DNS-t. A tárolt érték az, ahogy az URL-elemző szerializálja, amit küldtél, így a `https://acme.com` `https://acme.com/` alakban olvasható vissza.
eventTypesWebhookEvent[]- Mely események érik el ezt a végpontot: a `WEBHOOK_EVENTS` bármelyik neve. A `POST /webhooks` a létező események számánál húzza meg a tömb korlátját, így eggyel több már 422 az `eventTypes` mezőn; a `PATCH` nem korlátozza. Csak a hossz korlátozott, az ismétlődő név pontosan úgy tárolódik és olvasható vissza, ahogy küldted. Az elhagyott vagy üres érték üres listaként tárolódik, ezért olvasható vissza `['*']` alakban, és minden `email.*` eseményt jelent az `email.replied` kivételével – ma tizennégyet –, a domain- és letiltási családokat pedig soha. A később hozzáadott család soha nem jut el olyan végpontra, amely nem nevezte meg, így egy integráció nem kezdhet el egy kiadás miatt olyan alakot fogadni, amelyet még soha nem látott.
descriptionstring- A végpont címkéje, legfeljebb 200 karakter, hogy a webhookok listája nevekként olvasódjon, ne URL-ek oszlopaként. Ha elhagyod, nullként tárolódik és úgy is jön vissza.
Válasz: CreatedWebhookResource
object'webhook'- Mindig `'webhook'`, ugyanaz a diszkriminátor, amelyet egy sima olvasás ad vissza, mert a titok csupán egy további kulcs a szokásos alakon, nem pedig saját objektumtípus. Azt, hogy jelen van-e a `secret`, az dönti el, melyik metódust hívtad, nem ez a mező.
idstring- A végpont azonosítója: `whe_`, majd 24 hexadecimális karakter. Minden más webhookhívás ezt várja: `get`, `update`, `delete`, `rotateSecret`, `test` és `listDeliveries`.
urlstring- A végpont úgy, ahogy tárolva van, miután átment a HTTPS- és a tiltotthoszt-ellenőrzésen. Az elemzett URL újraszerializált alakja, ezért ehhez az értékhez hasonlíts, ne az általad küldött stringhez.
descriptionstring | null- Az általad adott címke, vagy null, ha nem adtál. Az az `update`, amely kifejezetten nullt küld, visszaállítja nullra.
eventTypesWebhookEvent[] | ['*']- A feliratkozott események, vagy `['*']`, ha a végpont egyet sem nevezett meg. A `['*']` az, ahogy az üres tárolt lista olvasáskor megjelenik, visszaküldeni nem lehet, és a tizenhárom üzenetesemény áll mögötte, nem az egész katalógus. A `create` és az `update` kizárólag a szó szerinti eseményneveket fogadja el.
enabledboolean- Megkísérli-e a rendszer a kézbesítéseket; a letiltott végpontot az események kiküldésekor kihagyja, a titkát és a kézbesítési előzményeit pedig megtartja. Itt mindig igaz, mivel a `WebhookCreate` nem tartalmaz `enabled` mezőt, csak a `WebhookPatch`.
lastDeliveryAtstring | null- Az utolsó kézbesítési KÍSÉRLET ISO 8601 időbélyege, nem az utolsó sikeré. Sikertelen POST után is rákerül, tehát azt mondja meg, hogy a végpontot megpróbálták, azt pedig, hogy hogyan sikerült, a `listDeliveries` mondja meg. Az első kísérletig null, így a `create` válaszában mindig null.
createdAtstring- A végpont regisztrálásának ISO 8601 időbélyege. A `list` ennek a mezőnek az alapján, a legújabbtól kezdve adja vissza a végpontokat.
secretstring- Az a HMAC-SHA-256 kulcs, amely minden kézbesítés `X-OpenEmail-Signature` fejlécét aláírja: `whsec_`, majd 32 véletlen bájt base64url alakban, és ezt adod át a `verifyWebhookSignature` hívásnak. A `create` és a `rotateSecret` adja vissza, más semmi. Olvasás soha nem adja vissza, ezért most tárold el; az elveszett titkot csak a `rotateSecret` tudja lecserélni, amely a régit azonnal érvényteleníti.