Pāriet uz galveno saturu
Izmantojiet webhook izsaukumus, lai reaģētu uz asinhronām izmaiņām. Piegāde notiek vismaz vienu reizi, tāpēc dublēti, aizkavēti un nesakārtoti notikumi ir normāli.

Reģistrējiet tikai vajadzīgos notikumus

Izveidojiet galapunktu ar POST /v3/webhooks. Abonējiet tikai dokumentētus notikumus, kas vada jūsu integrāciju. Šis piemērs izmanto transfer.state_changed.
Create webhook endpoint
Saglabājiet atbildes data.id kā WEBHOOK_ID. Pieprasiet portāla URL no GET /v3/webhooks/portal ar API atslēgu, kurai ir webhooks:write, iegūstiet šī galapunkta parakstīšanas noslēpumu un glabājiet to atsevišķi no API atslēgas noslēpumu pārvaldniekā. Portāla URL pats par sevi piešķir piekļuvi, un tā derīgums beidzas pēc vienas stundas, tāpēc katru reizi pieprasiet jaunu un neglabājiet un nekopīgojiet to. Portāls grupē v3 notikumus pēc resursa: Customers, Capabilities, Accounts, Recipients, Transfers un API. Katram notikumam ir redzama tā datu shēma un piemērs. Mantotie notikumi ir atzīmēti kā novecojuši un uzskaitīti atsevišķā Legacy grupā. Ja jūsu galapunkts jau abonē mantotu notikumu, tas turpina to saņemt. Jauniem abonementiem izvēlieties v3 notikumu nosaukumus.

Mainiet galapunkta notikumus

Nolasiet vienu galapunktu ar GET /v3/webhooks/{webhookId}. Atbildei ir tāda pati events struktūra kā GET /v3/webhooks. Tā nekad neietver parakstīšanas noslēpumu. Nolasīšanai nepieciešams webhooks:read, un nezināmam galapunkta ID tā atgriež 404 not_found. Atjauniniet galapunktu ar PATCH /v3/webhooks/{webhookId}. Nosūtiet galveni Idempotency-Key. Atjauninājumiem nepieciešams webhooks:write.
  • Nosūtiet tikai events, lai saglabātu pašreizējo URL.
  • Nosūtiet tikai url, lai saglabātu pašreizējo notikumu izvēli.
  • events aizstāj visu izvēli. Vispirms nolasiet galapunktu un iekļaujiet katru notikumu, kas jums joprojām ir vajadzīgs.
  • Jauniem abonementiem jāizmanto v3 notikumu nosaukumi.
  • Varat saglabāt mantota notikuma nosaukumu, ja galapunkts to jau abonē. Jauna mantota nosaukuma pievienošana atgriež 400 validation_error.
Šis pamatteksts saglabā URL un aizstāj izvēli:
Request body

Pārbaudiet pirms parsēšanas

Swipelux piegādā jaunas webhook integrācijas caur Svix. Pārbaudiet neapstrādāto pieprasījuma pamattekstu ar sava galapunkta parakstīšanas noslēpumu un šīm galvenēm:
  • svix-id
  • svix-timestamp
  • svix-signature
Neparsējiet JSON un neradiet blakusefektus, pirms verifikācija ir veiksmīga.
Verify signature
Noraidiet pieprasījumus ar trūkstošiem vai nederīgiem parakstiem. Uzturiet neapstrādāto pamattekstu pieejamu, līdz verifikācija ir pabeigta.

Saglabājiet, apstipriniet, pēc tam apstrādājiet

Uzstādiet unikalitātes ierobežojumu aploksnes id. Saglabājiet pārbaudīto aploksni, ātri atgrieziet 2xx, pēc tam apstrādājiet to asinhroni. Ja notikuma ID jau pastāv, apstipriniet piegādi, neatkārtojot pabeigtos blakusefektus. Atsāciet neizpildītos vai neveiksmīgos lokālos darbus caur savu atkārtotu mēģinājumu rindu. Neizmantojiet aploksnes lauku attempt kā deduplikācijas atslēgu vai transporta atkārtojumu skaitītāju.

Atkārtoti ielādējiet pašreizējo stāvokli

Webhook secība nav autoritatīva resursu vēsture. Izmantojiet resource.type un resource.id, lai atrastu objektu, pēc tam pirms sistēmas atjaunināšanas iegūstiet tā pašreizējo stāvokli. Pārveduma notikumam izsauciet GET /v3/transfers/{transferId}:
Refetch transfer
Vadiet klientam redzamo statusu un turpmākās darbības no pašreizējās API atbildes. Veidojiet blakusefektus tā, lai tie paliktu droši, ja divi izpildītāji apstrādā saistītus notikumus dažādā secībā.

Atjaunojiet piegādes

Izmantojiet GET /v3/webhooks/portal, lai atvērtu piegāžu žurnālus. Ar webhooks:write varat arī atkārtoti mēģināt neveiksmīgas piegādes vai sākt manuālu atkārtojumu. Atslēga ar tikai webhooks:read atver portālu, kas rāda piegādes, bet nevar tās atkārtoti mēģināt, atkārtot vai atklāt parakstīšanas noslēpumus. Katram atkārtojumam jāizet cauri tai pašai parakstu pārbaudei un noturīgai iesūtnei. Lai atgūtu pēc dīkstāves, atkārtojiet ietekmēto logu un atkārtoti ielādējiet katru minēto resursu. Pabeigtie notikumu ID paliek bez darbībām; nepabeigtie ieraksti tiek atsākti asinhroni. Tālāk pārbaudiet dublētās un nesakārtotās piegādes smilšu kastē, pēc tam pabeidziet Doties tiešraidē kontrolsarakstu.