Cost+Docs

Webhooks

Irċievi notifiki tal-istatus tal-ħlas f'ħin reali

Il-webhooks jippermettu lil-Cost+ tinnotifika s-server tiegħek f'ħin reali kull meta l-istatus ta' ordni tinbidel. Minflok tagħmel polling tal-API, tipprovdi URL u Cost+ tibgħat talba HTTP POST lejha kull meta jkun hemm aġġornament.

Kif Jaħdmu l-Webhooks

  1. Tispeċifika webhook_url meta toħloq ordni, jew tikkonfigura URL webhook default fil-livell tal-proġett.
  2. Meta l-istatus tal-ordni tinbidel (eż., minn new għal completed), Cost+ tibgħat talba POST lejn il-URL tal-webhook tiegħek.
  3. Is-server tiegħek jirċievi l-webhook, imbagħad isejjaħ l-API ta' Cost+ biex jiġbed id-dettalji sħaħ tal-ordni.
  4. Taġġorna s-sistema tiegħek ibbażat fuq l-istatus ivverifikat tal-ordni.

Qatt tafda l-payload tal-webhook waħdu biex tissodisfa ordni. Dejjem ivverifika l-istatus tal-ordni billi tagħmel talba GET /v1/orders/{id}/ wara li tirċievi webhook. Il-webhook huwa mekkaniżmu ta' notifika, mhux sors ta' verità.

Payload tal-Webhook

Il-korp tal-webhook huwa oġġett JSON li fih it-tip tal-avveniment u l-ID tal-ordni:

{
  "event": "status_changed",
  "order_id": "b9ae6...",
  "project_id": "proj_abc123"
}
QasamDeskrizzjoni
eventIt-tip ta' avveniment. Bħalissa status_changed għall-aġġornamenti tal-ordni.
order_idL-identifikatur uniku tal-ordni li l-istatus tagħha nbidlet.
project_idIl-proġett li l-ordni tappartjeni għalih.

Issettja l-URL tal-Webhook

Tista' tissettja l-URL tal-webhook b'żewġ modi:

Għal Kull Ordni

Inkludi l-qasam webhook_url meta toħloq ordni:

{
  "currency": "EUR",
  "amount": 1295,
  "webhook_url": "https://www.example.com/webhook"
}

Default tal-Proġett

Ikkonfigura URL webhook default fid-dashboard ta' Cost+ taħt is-settings tal-proġett. Din l-URL tintuża għall-ordnijiet kollha li ma jispeċifikawx il-webhook_url tagħhom stess.

Anke jekk għandek default fil-livell tal-proġett, tista' tieħu over fuq bażi ta' kull ordni billi tinkludi webhook_url fit-talba ta' ħolqien tal-ordni.

Loġika tar-Retry

Jekk is-server tiegħek ma jirrispondix b'kodiċi ta' status 2xx, Cost+ terġa tipprova l-konsenja tal-webhook:

  • Massimu ta' retries: 10 tentattivi
  • Intervall tar-retry: 2 minuti bejn kull tentattiv
  • Timeout tal-ewwel tentattiv: 4 sekondi
  • Timeout tat-tentattivi sussegwenti: 10 sekondi

Jekk l-10 tentattivi ta' retry kollha jfallu, il-webhook jiġi mmarkat bħala fallut. Xorta tista' tiġbed l-istatus tal-ordni fi kwalunkwe ħin billi tagħmel polling tal-API.

Kun żgur li l-endpoint tal-webhook tiegħek jirrispondi malajr (fi 4 sekondi għall-ewwel tentattiv). Agħmel kwalunkwe pproċessar li jieħu fit-tul b'mod asinkronu wara li tirritorna risposta 200 OK.

L-Aħjar Prattiċi

  • Dejjem ivverifika permezz tal-API. Meta tirċievi webhook, sejjaħ GET /v1/orders/\{order_id\}/ biex tikkonferma l-istatus kurrenti qabel tieħu azzjoni bħal li tibgħat prodotti jew tagħti aċċess.
  • Irritorna 200 malajr. Ikkonferma l-webhook b'risposta 200 immedjatament u pproċessa l-ordni b'mod asinkronu biex tevita timeouts.
  • Ittratta duplikati. L-endpoint tal-webhook tiegħek jista' jirċievi l-istess avveniment aktar minn darba. Kun żgur li l-loġika ta' pproċessar tiegħek hija idempotenti.
  • Uża HTTPS. Dejjem uża URL HTTPS għall-endpoint tal-webhook tiegħek biex tiżgura li l-payload jiġi trasmess b'mod sigur.
  • Irreġistra l-payloads tal-webhooks. Aħżen id-data tal-webhooks deħlin għall-debugging u skopijiet ta' awditjar.

Endpoints Relatati

On this page