Endpoints
`webhooks.list`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test` en `listDeliveries`.
Elke methode
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 is het ENIGE moment waarop het secret teruggegeven wordt, afgezien van rotateSecret. Een read echoot het nooit terug, dus sla het op voordat je iets anders doet. Laat eventTypes weg om elk event te ontvangen, latere inbegrepen.
rotateSecret heeft geen overlapvenster. Het oude secret werkt meteen niet meer, dus rol het nieuwe uit voordat je roteert. Er wordt nooit automatisch een nieuwe poging gedaan: een nieuwe poging zou een tweede keer roteren en het secret ongeldig maken dat de eerste poging teruggaf.
Waarop je je kunt abonneren
WEBHOOK_EVENTS wordt geëxporteerd zodat je de lijst kunt renderen. Events zijn events van de **mailbox**, niet van deze API: email.received vuurt voor mail die in de app binnenkomt, en email.sent vuurt voor een bericht dat de composer verstuurd heeft. Je abonneren is niet hetzelfde als je eigen API-verkeer bekijken.
Aantonen dat het werkt
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)Een responseCode van null betekent dat er helemaal geen respons was (DNS, TLS, een timeout), wat iets anders is dan een respons die 0 zei. Elke rij draagt attempt en maxAttempts, dus meerdere rijen kunnen één event beschrijven: de payload.id die ze delen is het event, en het pogingnummer is de poging.
Parameters: webhooks.create
urlstringverplicht- Waarheen bezorgingen ge-POST worden. Alleen HTTPS, en de host mag niet `localhost` zijn, geen `.localhost`/`.local`/`.internal`-naam, en geen loopback-, privé-, CGNAT- of link-local IP-literal. Dit is een server-side fetch naar een adres dat jij aanlevert, dus die gevallen zijn een 422 op `url`; de controle leest de hostname zoals hij geschreven is en doet nooit een DNS-lookup. Wat opgeslagen wordt is de serialisatie door de URL-parser van wat je stuurde, dus `https://acme.com` komt terug als `https://acme.com/`.
eventTypesWebhookEvent[]- Welke events dit endpoint bereiken: elk van de namen in `WEBHOOK_EVENTS`. `POST /webhooks` begrenst de array op het aantal events dat bestaat, dus één meer is een 422 op `eventTypes`; `PATCH` begrenst hem niet. Alleen de lengte is begrensd, en een herhaalde naam wordt precies zo opgeslagen en teruggelezen als je hem stuurde. Weggelaten of leeg wordt opgeslagen als een lege lijst, en daarom leest hij terug als `['*']`, en dat betekent elk `email.*`-event behalve `email.replied`, vandaag veertien, en nooit de domein- of suppressiefamilies. Een familie die later toegevoegd wordt bereikt nooit een endpoint dat haar niet genoemd heeft, dus een integratie kan door een release niet ineens een vorm gaan ontvangen die ze nog nooit gezien heeft.
descriptionstring- Een label voor het endpoint, maximaal 200 tekens, zodat een lijst met webhooks als namen leest in plaats van als een kolom URLs. Weggelaten wordt het als null opgeslagen en teruggegeven.
Respons: CreatedWebhookResource
object'webhook'- Altijd `'webhook'`, dezelfde discriminator die een gewone read teruggeeft, omdat het secret één extra sleutel op de gewone vorm is en geen eigen objecttype. Of `secret` aanwezig is, wordt bepaald door welke methode je aanriep, niet door dit veld.
idstring- De identifier van het endpoint: `whe_` gevolgd door 24 hexadecimale tekens. Elke andere webhook-aanroep neemt hem aan: `get`, `update`, `delete`, `rotateSecret`, `test` en `listDeliveries`.
urlstring- Het endpoint zoals het opgeslagen is, nadat het de HTTPS- en geblokkeerde-hostcontroles doorstaan heeft. Het is de geparste URL opnieuw geserialiseerd, dus vergelijk met deze waarde en niet met de string die je stuurde.
descriptionstring | null- Het label dat je eraan gaf, of null als je er geen gaf. Een `update` die een expliciete null stuurt, zet het weer terug op null.
eventTypesWebhookEvent[] | ['*']- De geabonneerde events, of `['*']` wanneer het endpoint er geen genoemd heeft. `['*']` is hoe een lege opgeslagen lijst bij het lezen weergegeven wordt en kan niet teruggestuurd worden, en het staat voor de dertien berichtevents en niet voor de hele catalogus. `create` en `update` accepteren alleen de letterlijke eventnamen.
enabledboolean- Of bezorgingen geprobeerd worden; een uitgeschakeld endpoint wordt overgeslagen wanneer events verstuurd worden en behoudt zijn secret en zijn bezorggeschiedenis. Hier altijd true, omdat `WebhookCreate` geen `enabled` heeft en alleen `WebhookPatch` wel.
lastDeliveryAtstring | null- ISO 8601-timestamp van de laatste bezorgPOGING, niet van het laatste succes. Hij wordt ook na een mislukte POST gezet, dus hij vertelt je dat het endpoint geprobeerd is en `listDeliveries` vertelt je hoe het afliep. Null tot de eerste poging, en dus altijd null bij `create`.
createdAtstring- ISO 8601-timestamp van wanneer het endpoint geregistreerd is. `list` geeft endpoints op dit veld nieuwste eerst terug.
secretstring- De HMAC-SHA-256-sleutel die de `X-OpenEmail-Signature` van elke bezorging ondertekent: `whsec_` gevolgd door 32 willekeurige bytes in base64url, en wat je aan `verifyWebhookSignature` geeft. Wordt teruggegeven door `create` en `rotateSecret` en door niets anders. Een read echoot hem nooit terug, dus sla hem nu op; een verloren secret kan alleen vervangen worden met `rotateSecret`, wat het oude meteen ongeldig maakt.