Ruby

Endpoint-et

`webhooks.list`, `list_all`, `iterate`, `get`, `create`, `update`, `delete`, `rotate_secret`, `test`, `get_delivery` dhe `replay_delivery`, si dhe regjistrat e dërgesave dhe të aktivitetit.

Çdo metodë

webhooks.rb

endpoint = client.webhooks.create(  url: "https://acme.com/hooks/mail",  eventTypes: ["email.sent", "email.bounced"],  description: "Billing service") File.write(".openemail-webhook-secret", endpoint[:secret]) client.webhooks.listclient.webhooks.get(endpoint[:id])client.webhooks.update(endpoint[:id], enabled: false)client.webhooks.test(endpoint[:id])latest = client.webhooks.list_deliveries(endpoint[:id], limit: 1).items.firstclient.webhooks.get_delivery(endpoint[:id], latest[:id])client.webhooks.replay_delivery(endpoint[:id], latest[:id])rotated = client.webhooks.rotate_secret(endpoint[:id])File.write(".openemail-webhook-secret", rotated[:secret])client.webhooks.delete(endpoint[:id])

create është hera E VETME kur kthehet sekreti, përveç rotate_secret. Një lexim nuk e kthen kurrë, ndaj ruajeni para se të bëni çdo gjë tjetër. Lëreni jashtë eventTypes për grupin e parazgjedhur, çdo ngjarje email.* përveç email.replied. email.replied, domain.*, suppression.*, file.* dhe form.* arrijnë te një endpoint vetëm kur ai i emërton.

rotate_secret nuk ka dritare mbivendosjeje. Sekreti i vjetër pushon së funksionuari menjëherë, ndaj vendoseni të riun në prodhim para se të bëni rrotullimin. Nuk riprovohet kurrë automatikisht: një riprovim do të bënte një rrotullim të dytë dhe do ta zhvlerësonte sekretin që ktheu përpjekja e parë.

As create nuk riprovohet, ndaj një dështim i rrjetit mund të lërë një endpoint të krijuar me një sekret që nuk e patë kurrë. Kontrolloni list para se ta krijoni sërish. Një hapësirë pune mban 10 endpoint-e si parazgjedhje, dhe i radhës përtej kufirit jep një 422 workspace_limit_reached.

Te çfarë mund të abonoheni

OpenEmail::WEBHOOK_EVENTS është një Hash i ngrirë me çdo emër ngjarjeje, që ta shfaqni listën pa kërkesë, dhe webhooks.list_events kthen të njëjtët emra me një fjali për secilin, plus kufijtë të cilëve u nënshtrohet një endpoint. Ngjarjet janë ngjarje të **kutisë postare**, jo të kësaj API-je: email.received aktivizohet për postën që mbërrin në aplikacion, dhe email.sent aktivizohet për një mesazh që e dërgoi kompozuesi. Abonimi nuk është e njëjta gjë me vëzhgimin e trafikut tuaj të API-së.

file.uploaded aktivizohet kur një skedar vendoset te faqja Skedarët, dhe file.deleted kur një skedar fshihet. data e tyre mban fileId, filename, mimeType, sizeBytes, direction, to, threadId, messageId, dhe uploadedAt ose deletedAt. to është adresa së cilës i përket skedari, ose nil për një skedar që i përket gjithë hapësirës së punës.

Ngjarjet e skedarëve nuk janë në grupin e parazgjedhur, ndaj një endpoint i merr vetëm kur i emërton te eventTypes. Një endpoint i kufizuar në disa adresa njoftohet vetëm për skedarët e atyre adresave, ndaj një ngarkim për gjithë hapësirën e punës, me to nil, nuk i dërgohet.

form.submitted aktivizohet kur dikush regjistrohet përmes njërit prej formularëve tuaj, dhe form.confirmed kur një regjistrim në pritje hyn në audienca, sepse personi hapi lidhjen e konfirmimit ose sepse e miratuat ju. data e form.submitted mban formId, formName, submissionId, email, status, answers, audienceIds, sourceUrl dhe submittedAt. data e form.confirmed mban formId, formName, submissionId, email, audienceIds, via, që është link ose approval, dhe confirmedAt.

Një regjistrim te një formular pa konfirmim të dyfishtë dërgon form.submitted me status added dhe asnjë form.confirmed, ndaj trajtojeni atë çift si çastin kur dikush bashkohet. Kush regjistrohet sërish para konfirmimit ruan të njëjtin submissionId, dhe form.submitted dërgohet sërish vetëm kur përgjigjet e tij kanë ndryshuar. Ngjarjet e formularëve nuk janë në grupin e parazgjedhur, dhe një endpoint i kufizuar në disa adresa nuk i merr kurrë, sepse regjistrimet i përkasin gjithë hapësirës së punës.

Si provohet se funksionon

webhook_test.rb

result = client.webhooks.test("whe_3f9c2a7b1e4d8f60a5c7b92d")puts result.dig(:delivery, :status), result.dig(:delivery, :responseCode) client.webhooks.iterate_deliveries("whe_3f9c2a7b1e4d8f60a5c7b92d") do |delivery|  puts "#{delivery[:eventType]} #{delivery[:status]} #{delivery[:responseCode]} #{delivery[:error]}"end

test poston një ngjarje sintetike të nënshkruar email.sent dhe pret që përpjekja të përfundojë. Kthehet normalisht, çfarëdo që të jetë përgjigjur marrësi juaj, ndaj degëzoni sipas delivery[:status], jo sipas faktit nëse thirrja ngriti gabim. Një 4xx është një përgjigje e dobishme: URL-ja është e arritshme dhe refuzimi erdhi nga handler-i juaj, shpesh nga kontrolli i tij i nënshkrimit.

Një responseCode nil do të thotë se nuk pati fare përgjigje (DNS, TLS, një skadim kohe), që është fakt tjetër nga një përgjigje që tha 0. Çdo rresht mbart attempt dhe maxAttempts, ndaj disa rreshta mund të përshkruajnë një ngjarje: i njëjti eventId në to është ngjarja, dhe numri i përpjekjes është prova. nextAttemptAt tregon kur pritet riprovimi automatik pas një rreshti.

Dërgimi sërish

webhook_replay.rb

detail = client.webhooks.get_delivery("whe_3f9c2a7b1e4d8f60a5c7b92d", "whd_8c1e4a7f2b9d3e6a0c5f1b28")p detail[:payload], detail[:responseBody], detail[:replayRefusal] replay = client.webhooks.replay_delivery("whe_3f9c2a7b1e4d8f60a5c7b92d", "whd_8c1e4a7f2b9d3e6a0c5f1b28")p replay.dig(:delivery, :status), replay.dig(:delivery, :responseCode)

Një dërgesë që vazhdon të dështojë provohet deri në 8 herë: sapo ndodh, pastaj pas 1 minute, 5 minutash, 30 minutash, 2 orësh, 5 orësh, 10 orësh dhe 10 orësh, rreth 27 orë e gjysmë gjithsej. Përsëritet vetëm një dështim që ia vlen të përsëritet: asnjë përgjigje, 408, 425, 429 ose një 5xx. Një riluajtje e dërgon sërish ngjarjen e ruajtur me të njëjtat id, type, createdAt dhe data, ndaj një marrës që i hedh id-të që i ka trajtuar tashmë e trajton si ngjarjen që e njeh. E re është vetëm nënshkrimi.

replay_delivery dërgon një ngjarje tani dhe kthen atë që u përgjigj serveri juaj. Funksionon edhe mbi një përpjekje të dorëzuar dhe nuk riprovohet kurrë. Para se të dërgojë, riprovimet automatike të asaj ngjarjeje që nuk kanë nisur ende pezullohen: mbeten të anuluara nëse riluajtja dorëzohet, dhe rifillojnë sipas orarit të tyre nëse dështon.
Nëse në atë çast po dërgohet një riprovim automatik i së njëjtës ngjarje, replay_delivery nuk dërgon asgjë dhe ngre një 409 retry_in_progress, dhe sa kohë që një riluajtje tjetër e saj po dërgohet ende, ngre një 409 replay_in_progress, që marrësi juaj të mos marrë kurrë dy kopje njëherësh, as nga dy riluajtje të dërguara në të njëjtin çast. Prisni disa sekonda dhe lexoni get_delivery, sepse ai riprovim ose ajo riluajtje mund ta dorëzojë. Riluajtja bëhet një ngjarje në një kohë: asnjë thirrje nuk i dërgon sërish të gjitha dërgesat e dështuara.
Ngre gjithashtu një 409 për një endpoint të fikur (webhook_disabled), për një ngjarje që endpoint-i nuk e dëgjon më (event_not_subscribed) ose nuk e mbulon më (event_out_of_scope), dhe për një përpjekje pa ngjarje të ruajtur (delivery_not_replayable). get_delivery e raporton paraprakisht atë përgjigje si replayRefusal.

Gem-i nuk e riprovon kurrë vetë replay_delivery, sepse një riprovim pas një përgjigjeje të humbur do ta dërgonte sërish ngjarjen.

Parametrat: webhooks.create

urlStringe detyrueshme: Ku POST-ohen dërgesat. Vetëm HTTPS, dhe host-i nuk mund të jetë `localhost`, një emër `.localhost`, `.local` ose `.internal`, apo një IP literale loopback, private, CGNAT ose link-local. Kjo është një kërkesë nga ana e serverit drejt një adrese që e jepni ju, ndaj ato japin një 422 `invalid_webhook_url` te `url`. Kontrolli e lexon emrin e host-it ashtu siç është shkruar, dhe çdo dërgesë e kërkon sërish host-in dhe refuzon të dërgojë te një adresë në njërin nga ato diapazone. Dërgesat nuk ndjekin kurrë ridrejtime, ndaj regjistroni adresën përfundimtare. Ajo që ruhet është serializimi i parserit të URL-së për atë që dërguat, ndaj `https://acme.com` lexohet prapë si `https://acme.com/`.
eventTypesArray<String>: Cilat ngjarje mbërrijnë te ky endpoint: cilado prej vlerave te `OpenEmail::WEBHOOK_EVENTS`. `create` e kufizon Array-n te numri i ngjarjeve që ekzistojnë, ndaj një më shumë se aq jep një 422 te `eventTypes`, ndërsa `update` nuk e kufizon. Kufizohet vetëm gjatësia, dhe një emër i përsëritur ruhet dhe lexohet prapë saktësisht ashtu siç e dërguat. I lënë jashtë ose bosh, ruhet si listë bosh, prandaj lexohet prapë si `["*"]`, dhe do të thotë çdo ngjarje `email.*` përveç `email.replied`, katërmbëdhjetë sot, dhe kurrë familjet domain, suppression, file ose form. Një familje e shtuar më vonë nuk mbërrin kurrë te një endpoint që nuk e ka emërtuar, ndaj një integrim nuk mund të nisë të marrë një formë që nuk e ka parë kurrë, thjesht për shkak të një publikimi.
descriptionString: Një etiketë për endpoint-in, me më së shumti 200 karaktere, që një listë webhook-esh të lexohet si emra dhe jo si një kolonë URL-sh. Kur lihet jashtë, ruhet dhe kthehet si nil.
addressAllowlistArray<String>: Adresa të veçanta për të cilat njoftohet ky endpoint. Një ngjarje dorëzohet kur adresa që ajo prek është në këtë listë, ose kur domeni i saj është te `domainAllowlist`. Lërini të dyja bosh dhe endpoint-i njoftohet për çdo adresë që zotëron hapësira e punës. Më së shumti 50, dhe një adresë që kjo hapësirë pune nuk e zotëron jep një 422 `invalid_parameter`.
domainAllowlistArray<String>: Domene të tëra për të cilat njoftohet ky endpoint, përfshirë adresat që u shtohen më vonë. Një domen mbart edhe ngjarjet e veta `domain.*`. Më së shumti 25.
api_keyString: E krijon endpoint-in me këtë çelës në vend të atij të klientit.

Përgjigjja: endpoint-i i krijuar

Një Hash me çelësa Symbol. get, list dhe update kthejnë të njëjtën formë pa secret.

objectString: Gjithmonë `webhook`, i njëjti dallues që kthen një lexim i thjeshtë, sepse sekreti është një çelës shtesë në formën e zakonshme dhe jo një lloj objekti më vete. Nëse `secret` është i pranishëm vendoset nga metoda që thirrët, jo nga kjo fushë.
idString: Identifikuesi i endpoint-it: `whe_` i ndjekur nga 24 karaktere hex. E merr çdo thirrje tjetër e webhook-ëve: `get`, `update`, `delete`, `rotate_secret`, `test`, `list_deliveries`, `list_all_deliveries`, `iterate_deliveries`, `get_delivery` dhe `replay_delivery`.
urlString: Endpoint-i siç është ruajtur, pasi kaloi kontrollet e HTTPS-së dhe të host-eve të bllokuar. Është URL-ja e analizuar dhe e serializuar sërish, ndaj krahasoni me këtë vlerë dhe jo me String-un që dërguat.
descriptionString or nil: Etiketa që i dhatë, ose nil nëse nuk i dhatë asnjë. Një `update` që dërgon `description: nil` e pastron.
eventTypesArray<String>: Ngjarjet e abonuara, ose `["*"]` kur endpoint-i nuk emërtoi asnjë. `["*"]` është mënyra si shfaqet në lexim një listë e ruajtur bosh dhe nuk mund të dërgohet prapë, dhe përfaqëson katërmbëdhjetë ngjarjet e mesazheve, jo gjithë katalogun. `create` dhe `update` pranojnë vetëm emrat literalë të ngjarjeve.
enabledBoolean: Nëse tentohen dërgesat. Një endpoint i çaktivizuar anashkalohet kur shpërndahen ngjarjet dhe ruan sekretin dhe historikun e dërgesave. Gjithmonë true këtu, sepse vetëm `update` merr `enabled`.
disabledAtString or nil: Kur serveri e fiku endpoint-in pas 100 dërgesash të dështuara radhazi. nil sa kohë që është ndezur, dhe kur e fikët vetë.
disabledReasonString or nil: Pse e fiku serveri. nil sa herë që `disabledAt` është nil.
consecutiveFailuresInteger: Dërgesa të dështuara radhazi. Çdo ngjarje e dorëzuar e rivendos në 0, dhe po ashtu edhe `update` me `enabled: true`.
addressAllowlistArray<String>: Adresat e veçanta për të cilat njoftohet ky endpoint.
domainAllowlistArray<String>: Domenet e tëra për të cilat njoftohet ky endpoint. Kur të dyja listat janë bosh, kjo do të thotë çdo adresë që zotëron hapësira e punës.
lastDeliveryAtString or nil: Vula kohore ISO 8601 e PËRPJEKJES së fundit të dërgesës, jo e suksesit të fundit. Vendoset edhe pas një POST-i të dështuar, ndaj ju tregon se endpoint-i u provua, dhe `list_deliveries` ju tregon si shkoi. nil deri në përpjekjen e parë, dhe prandaj gjithmonë nil te `create`.
createdAtString: Vula kohore ISO 8601 e çastit kur u regjistrua endpoint-i. `list` i kthen endpoint-et nga më i riu te më i vjetri sipas kësaj fushe.
secretString: Çelësi HMAC-SHA-256 që nënshkruan `X-OpenEmail-Signature` të çdo dërgese: `whsec_` i ndjekur nga 43 karaktere base64url, dhe ai që i jepni `OpenEmail.verify_webhook_signature`, bashkë me prefiksin. Kthehet nga `create` dhe `rotate_secret` dhe nga asgjë tjetër. Një lexim nuk e kthen kurrë, ndaj ruajeni tani. Një sekret i humbur mund të zëvendësohet vetëm me `rotate_secret`, që e zhvlerëson menjëherë të vjetrin.

Filtrimi i regjistrave

webhook_logs.rb

failed = client.webhooks.list_workspace_deliveries(status: "failed", since: Time.now - 86_400)p failed.items.map { |delivery| [delivery[:endpointId], delivery[:eventType], delivery[:responseCode]] } history = client.webhooks.list_activity("whe_3f9c2a7b1e4d8f60a5c7b92d")p history.items.map { |change| [change[:type], change.dig(:actor, :label)] }

list_deliveries lexon një endpoint dhe list_workspace_deliveries çdo endpoint, ose ata që emërton endpoint_ids:, dhe të dyja marrin status:, since: dhe until:, filtrat e skedës Dërgesat në konsolë. list_activity dhe list_workspace_activity lexojnë regjistrin e auditimit: kush krijoi, ndryshoi, ndezi a fiku, rrotulloi, testoi, riluajti ose hoqi çfarë. Secila ka pranë një version list_all_ dhe një iterate_, dhe çdo rresht i regjistrit të hapësirës së punës mbart endpointId. webhooks.stats kthen numrat pas skedës Analitika për një dritare kohore që e zgjidhni ju.

since: dhe until: marrin një Time, një DateTime ose një çast ISO 8601 si String, dhe një Date e Ruby-t do të thotë mesnatë UTC e asaj dite. until është fjalë e rezervuar e Ruby-t, por funksionon si argument me fjalë kyçe si çdo tjetër: list_deliveries(id, since: start, until: finish).