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
- Tispeċifika
webhook_urlmeta toħloq ordni, jew tikkonfigura URL webhook default fil-livell tal-proġett. - Meta l-istatus tal-ordni tinbidel (eż., minn
newgħalcompleted), Cost+ tibgħat talba POST lejn il-URL tal-webhook tiegħek. - Is-server tiegħek jirċievi l-webhook, imbagħad isejjaħ l-API ta' Cost+ biex jiġbed id-dettalji sħaħ tal-ordni.
- 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"
}| Qasam | Deskrizzjoni |
|---|---|
event | It-tip ta' avveniment. Bħalissa status_changed għall-aġġornamenti tal-ordni. |
order_id | L-identifikatur uniku tal-ordni li l-istatus tagħha nbidlet. |
project_id | Il-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
200immedjatament 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
- Oħloq Ordni — issettja l-
webhook_urlgħal kull ordni - Aġġorna Ordni — aġġorna l-URL tal-webhook fuq ordni eżistenti
- Skemi tal-Avvenimenti tal-Webhooks — format tal-payload għal
OrderStatusChangedEventuTransactionStatusChangedEvent