Endpoint-et
`webhooks.list`, `list_all`, `iterate`, `get`, `create`, `update`, `delete`, `rotate_secret`, `test`, `get_delivery` dhe `replay_delivery`, si edhe regjistrat e dorëzimeve dhe të aktivitetit.
Çdo metodë
from acme.secrets import store endpoint = client.webhooks.create({ 'url': 'https://acme.com/hooks/mail', 'eventTypes': ['email.sent', 'email.bounced'], 'description': 'Billing service',}) store(endpoint['secret']) client.webhooks.list()client.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'][0]client.webhooks.get_delivery(endpoint['id'], latest['id'])client.webhooks.replay_delivery(endpoint['id'], latest['id'])rotated = client.webhooks.rotate_secret(endpoint['id'])store(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ë riprovë do të bënte një rrotullim të dytë dhe do ta bënte të pavlefshëm sekretin që ktheu përpjekja e parë.
Te çfarë mund të abonoheni
WEBHOOK_EVENTS eksportohet që ta shfaqni listën. Ngjarjet janë ngjarje të **kutisë postare**, jo të kësaj API: email.received aktivizohet për postën që mbërrin në aplikacion, kurse email.sent aktivizohet për një mesazh që e dërgoi hartuesi. Abonimi nuk është e njëjta gjë me vëzhgimin e trafikut tuaj të API-së.
file.uploaded ndizet kur një skedar vendoset në faqen Skedarët, dhe file.deleted kur një skedar fshihet. Të dhënat e tyre janë FileEventData: 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 ndizet kur dikush regjistrohet përmes një prej formularëve tuaj, dhe form.confirmed kur një regjistrim në pritje hyn në audiencat, sepse personi hapi lidhjen e konfirmimit ose sepse ju e miratuat. form.submitted mbart FormSubmittedEventData: formId, formName, submissionId, email, status, answers, audienceIds, sourceUrl dhe submittedAt. form.confirmed mbart FormConfirmedEventData: 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.
Secila nga këto forma të dhënash është një TypedDict në openemail.types. Anotoni një ngjarje të verifikuar, për shembull, si WebhookPayload[FileEventData], dhe një kontrollues tipash e di se çfarë mban event['data'].
Si provohet se funksionon
result = client.webhooks.test('whe_…')delivery = result['delivery'] if delivery is not None: print(delivery['status'], delivery['responseCode']) for d in client.webhooks.iterate_deliveries('whe_…'): print(d['eventType'], d['status'], d['responseCode'], d['error'])Një responseCode i barabartë me None do të thotë se nuk pati fare përgjigje (DNS, TLS, një timeout), 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 të vetme: i njëjti eventId në të gjithë ata është ngjarja, kurse numri i përpjekjes është prova. nextAttemptAt tregon kur bie riprovimi automatik që vjen pas një rreshti.
Dërgimi sërish
detail = client.webhooks.get_delivery('whe_…', 'whd_…')print(detail['payload'], detail['responseBody'], detail['replayRefusal']) replay = client.webhooks.replay_delivery('whe_…', 'whd_…')print(replay['delivery']['status'], replay['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_deliverydë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_deliverynuk dërgon asgjë dhe refuzohet me 409retry_in_progress, dhe sa kohë që një riluajtje tjetër e saj po dërgohet ende, refuzohet me 409replay_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 lexoniget_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 dorëzimet e dështuara. - Gjithashtu refuzon me 409 një endpoint të fikur (
webhook_disabled), një ngjarje që endpoint-i nuk e dëgjon më (event_not_subscribed) ose nuk e mbulon më (event_out_of_scope), dhe një përpjekje pa ngjarje të ruajtur (delivery_not_replayable).get_deliverye jep këtë përgjigje paraprakisht sireplayRefusal.
SDK-ja nuk e riprovon kurrë vetë replay_delivery, sepse një riprovë pas një përgjigjeje të humbur do ta dërgonte ngjarjen sërish.
Çdo refuzim ngre OpenEmailApiError me status 409, is_conflict true dhe arsyen si code, një nga vlerat në WEBHOOK_REPLAY_ERROR_CODES.
Parametrat: webhooks.create
urlstre detyrueshme- Ku POST-ohen dërgesat. Vetëm HTTPS, dhe host-i nuk mund të jetë `localhost`, një emër `.localhost`/`.local`/`.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 janë një 422 te `url`; kontrolli e lexon emrin e host-it ashtu siç është shkruar dhe nuk zgjidh kurrë DNS. 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/`.
eventTypeslist[WebhookEvent]- Cilat ngjarje mbërrijnë te ky endpoint: cilido prej emrave te `WEBHOOK_EVENTS`. `POST /webhooks` e kufizon array-n te numri i ngjarjeve që ekzistojnë, ndaj një më shumë se aq është një 422 te `eventTypes`; `PATCH` nuk e kufizon. Kufizohet vetëm gjatësia, kurse 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 ose file. 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.
descriptionstr- Një etiketë për endpoint-in, me më së shumti 200 karaktere, që një listë webhook-esh të lexohet si emra e jo si një kolonë URL-sh. Nëse lihet jashtë, ruhet dhe kthehet si null.
Përgjigjja: CreatedWebhookResource
objectLiteral['webhook']- Gjithmonë `'webhook'`, i njëjti diskriminues që kthen një lexim i thjeshtë, sepse sekreti është një çelës shtesë mbi formën e zakonshme e jo një tip objekti më vete. Nëse `secret` është i pranishëm apo jo, vendoset nga metoda që thirrët, jo nga kjo fushë.
idstr- Identifikuesi i endpoint-it: `whe_` i ndjekur nga 24 karaktere hex. E marrin të gjitha thirrjet e tjera të webhook-ut: `get`, `update`, `delete`, `rotate_secret`, `test`, `list_deliveries`, `list_all_deliveries`, `iterate_deliveries`, `get_delivery` dhe `replay_delivery`.
urlstr- Endpoint-i ashtu siç është ruajtur, pasi ka kaluar kontrollet e HTTPS dhe të host-eve të bllokuar. Është URL-ja e parsuar e riserializuar, ndaj krahasoni me këtë vlerë e jo me vargun që dërguat.
descriptionstr | None- Etiketa që i vutë, ose null nëse nuk i vutë asnjë. Një `update` që dërgon një null të shprehur e pastron atë sërish në null.
eventTypeslist[WebhookEvent] | ['*']- 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 e ruan sekretin e vet e historikun e dërgesave. Gjithmonë true këtu, meqë `WebhookCreate` nuk ka `enabled` dhe e ka vetëm `WebhookPatch`.
lastDeliveryAtstr | None- Vula kohore ISO 8601 e PËRPJEKJES së fundit për dërgesë, jo e suksesit të fundit. Ajo vihet edhe pas një POST-i të dështuar, ndaj ju thotë se endpoint-i u provua, kurse `list_deliveries` ju thotë si shkoi. Null derisa të bëhet përpjekja e parë, prandaj gjithmonë null te `create`.
createdAtstr- 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.
secretstr- Çelësi HMAC-SHA-256 që nënshkruan `X-OpenEmail-Signature`-n e çdo dërgese: `whsec_` i ndjekur nga 32 bajt të rastësishëm në base64url, dhe ai që i jepni `verify_webhook_signature`. Kthehet nga `create` dhe `rotate_secret` e 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 bën të pavlefshëm të vjetrin menjëherë.
Filtrimi i regjistrave
from datetime import datetime, timedelta, timezone failed = client.webhooks.list_workspace_deliveries( status='failed', since=datetime.now(timezone.utc) - timedelta(days=1),)print(len(failed['items'])) history = client.webhooks.list_activity('whe_…')print([(change['type'], change['actor']['label'] if change['actor'] else None) for change in history['items']])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 Dorëzimet të konsolës. list_activity dhe list_workspace_activity lexojnë regjistrin e auditimit: kush krijoi, ndryshoi, fiku a ndezi, rrotulloi, testoi, ridërgoi ose hoqi çfarë. Secila ka një list_all_… dhe një iterate_… pranë, dhe çdo rresht i regjistrit të hapësirës së punës mban endpointId.
since= dhe until= marrin një datetime ose një varg ISO 8601. Një datetime naiv lexohet si ora vendore dhe konvertohet në UTC, ndaj jepni një me zonë kohore, si më sipër.
Referencë
webhooks.list()Referenca e plotëwebhooks.list_all()Referenca e plotëwebhooks.iterate()Referenca e plotëwebhooks.get()Referenca e plotëwebhooks.create()Referenca e plotëwebhooks.update()Referenca e plotëwebhooks.delete()Referenca e plotëwebhooks.rotate_secret()Referenca e plotëwebhooks.test()Referenca e plotëwebhooks.list_deliveries()Referenca e plotëwebhooks.list_all_deliveries()Referenca e plotëwebhooks.iterate_deliveries()Referenca e plotëwebhooks.get_delivery()Referenca e plotëwebhooks.replay_delivery()Referenca e plotëwebhooks.list_workspace_deliveries()Referenca e plotëwebhooks.list_all_workspace_deliveries()Referenca e plotëwebhooks.iterate_workspace_deliveries()Referenca e plotëwebhooks.list_activity()Referenca e plotëwebhooks.list_all_activity()Referenca e plotëwebhooks.iterate_activity()Referenca e plotëwebhooks.list_workspace_activity()Referenca e plotëwebhooks.list_all_workspace_activity()Referenca e plotëwebhooks.iterate_workspace_activity()Referenca e plotë