PHP

Endpoint-et

`webhooks->list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test`, `getDelivery` dhe `replayDelivery`, si dhe regjistrat e dërgesave dhe të aktivitetit.

Çdo metodë

webhooks.php

use OpenEmail\Constants\WebhookEvents; $endpoint = $client->webhooks->create([    'url' => 'https://acme.com/hooks/mail',    'eventTypes' => [WebhookEvents::EMAIL_SENT, WebhookEvents::EMAIL_BOUNCED],    'description' => 'Billing service',]); file_put_contents('.openemail-webhook-secret', $endpoint['secret']); $client->webhooks->list();$client->webhooks->get($endpoint['id']);$client->webhooks->update($endpoint['id'], ['enabled' => false]);$client->webhooks->test($endpoint['id']); foreach ($client->webhooks->listDeliveries($endpoint['id'], limit: 1) as $latest) {    $client->webhooks->getDelivery($endpoint['id'], $latest['id']);    $client->webhooks->replayDelivery($endpoint['id'], $latest['id']);} $rotated = $client->webhooks->rotateSecret($endpoint['id']);file_put_contents('.openemail-webhook-secret', $rotated['secret']); $client->webhooks->delete($endpoint['id']);

create është hera E VETME kur kthehet sekreti, përveç rotateSecret. 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.

list kthen një OpenEmail\Result\Page, listAll i kthen të gjithë endpoint-et në një array të vetëm, dhe iterate kthen një Generator që jep endpoint-et një nga një. create dhe update e marrin trupin si një array të vetëm me emrat e API-së, dhe çdo endpoint kthehet si array me çelësa në camelCase.

rotateSecret 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ë riprovë do të bënte një rrotullim të dytë dhe do ta bënte të pavlefshëm 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\Constants\WebhookEvents e emërton çdo ngjarje si konstante, dhe WebhookEvents::values() i liston, që ta shfaqni listën pa kërkesë. webhooks->listEvents kthen të njëjtët emra me një etiketë për secilin, plus kufijtë të cilëve u nënshtrohet një endpoint, te maxEndpoints, maxAddresses dhe maxDomains. 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 null 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 null, 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.php

$result = $client->webhooks->test('whe_3f9c2a7b1e4d8f60a5c7b92d');echo $result['delivery']['status'], ' ', $result['delivery']['responseCode'] ?? 'no response', PHP_EOL; foreach ($client->webhooks->iterateDeliveries('whe_3f9c2a7b1e4d8f60a5c7b92d') as $delivery) {    echo $delivery['eventType'], ' ', $delivery['status'], ' ', $delivery['responseCode'] ?? '-', ' ', $delivery['error'] ?? '', PHP_EOL;}

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 $result['delivery']['status'], jo sipas faktit nëse thirrja hodhi përjashtim. 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 null 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.php

$detail = $client->webhooks->getDelivery('whe_3f9c2a7b1e4d8f60a5c7b92d', 'whd_8c1e4a7f2b9d3e6a0c5f1b28');echo json_encode($detail['payload'], JSON_THROW_ON_ERROR), PHP_EOL;echo $detail['responseBody'] ?? 'no answer', ' ', $detail['replayRefusal']['code'] ?? 'replayable', PHP_EOL; $replay = $client->webhooks->replayDelivery('whe_3f9c2a7b1e4d8f60a5c7b92d', 'whd_8c1e4a7f2b9d3e6a0c5f1b28');echo $replay['delivery']['status'], ' ', $replay['delivery']['responseCode'] ?? 'no response', PHP_EOL;

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.

replayDelivery 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, replayDelivery nuk dërgon asgjë dhe hedh një 409 retry_in_progress, dhe sa kohë që një riluajtje tjetër e saj po dërgohet ende, hedh 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 getDelivery, 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.
Hedh 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). Secili është një ConflictException, dhe OpenEmail\Constants\WebhookReplayErrorCodes i emërton kodet. getDelivery e raporton paraprakisht atë përgjigje si replayRefusal, null kur një riluajtje do të vazhdonte dhe përndryshe një array me code dhe message.

Paketa nuk e riprovon kurrë vetë replayDelivery, 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, NAT të nivelit të operatorit, link-local, multicast ose lokale unike. 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: Cilat ngjarje mbërrijnë te ky endpoint: cilado prej vlerave te `OpenEmail\Constants\WebhookEvents`. `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 null. Lëreni çelësin jashtë në vend që të jepni null: klienti e dërgon null-in ashtu siç është, dhe `create` e refuzon me një 422.
addressAllowlistarray: 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: 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.
apiKeystring: Një argument me emër pranë array-t dhe jo një çelës brenda tij: e krijon endpoint-in me këtë çelës API në vend të atij të klientit.

Përgjigjja: endpoint-i i krijuar

Një array me çelësa në camelCase. 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`, `rotateSecret`, `test`, `listDeliveries`, `listAllDeliveries`, `iterateDeliveries`, `getDelivery` dhe `replayDelivery`.
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 null: Etiketa që i dhatë, ose null nëse nuk i dhatë asnjë. Një `update` që dërgon `'description' => null` e pastron.
eventTypesarray: 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ë; ai qëndron për të katërmbëdhjetë ngjarjet e mesazheve e jo për gjithë katalogun. `create` dhe `update` pranojnë vetëm emrat literalë të ngjarjeve.
enabledbool: 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 null: Kur serveri e fiku endpoint-in pas 100 dërgesash të dështuara radhazi. null sa kohë që është ndezur, dhe kur e fikët vetë.
disabledReasonstring or null: Pse e fiku serveri. null sa herë që `disabledAt` është null.
consecutiveFailuresint: Dërgesa të dështuara radhazi. Çdo ngjarje e dorëzuar e rivendos në 0, dhe po ashtu edhe `update` me `enabled` të vendosur në true.
addressAllowlistarray: Adresat e veçanta për të cilat njoftohet ky endpoint.
domainAllowlistarray: 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 null: 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 `listDeliveries` ju tregon si shkoi. null deri në përpjekjen e parë, dhe prandaj gjithmonë null 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::verifyWebhookSignature`, bashkë me prefiksin. Kthehet nga `create` dhe `rotateSecret` 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 `rotateSecret`, që e zhvlerëson menjëherë të vjetrin.

Filtrimi i regjistrave

webhook_logs.php

$failed = $client->webhooks->listWorkspaceDeliveries(status: 'failed', since: new \DateTimeImmutable('-1 day')); foreach ($failed as $delivery) {    echo $delivery['endpointId'], ' ', $delivery['eventType'], ' ', $delivery['responseCode'] ?? '-', PHP_EOL;} $history = $client->webhooks->listActivity('whe_3f9c2a7b1e4d8f60a5c7b92d'); foreach ($history as $change) {    echo $change['type'], ' ', $change['actor']['label'] ?? 'OpenEmail', PHP_EOL;}

listDeliveries lexon një endpoint dhe listWorkspaceDeliveries çdo endpoint, ose ata që emërton endpointIds:, si array ose si një string i vetëm i ndarë me presje, dhe të dyja marrin status: (delivered ose failed), since: dhe until:, filtrat e skedës Dërgesat në konsolë. listActivity dhe listWorkspaceActivity lexojnë regjistrin e auditimit: kush krijoi, ndryshoi, ndezi a fiku, rrotulloi, testoi, riluajti ose hoqi çfarë. Secila ka pranë një version listAll dhe një iterate, si listAllDeliveries dhe iterateDeliveries, 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ë DateTimeInterface ose një string ISO 8601, dhe një string që mban vetëm një datë do të thotë mesnatë UTC e asaj dite. until: duhet të jetë më vonë se since:, përndryshe thirrja hedh një InvalidRequestException me errorCode të vendosur në invalid_parameter.