Piegādes atskaišu saņemšana, izmantojot webhook

Konta iestatījumos varat norādīt HTTP(S) adresi priekš "webhook", kas mūsu pusē tiks izsaukts ikreiz, kad parādīsies jauna piegādes atskaite ziņojumam, kas nosūtīts caur jūsu API kontu.

Atkarībā no Jūsu ugunsmūra iestatījumiem, varētu būt noderīgi pievienot mūsu IP adreses izņēmumiem (whitelist), lai šo pieprasījumu saņemšana vienmēr būtu veiksmīga.

Uz klienta norādīto adresi atskaites tiks piegādātas kā HTTP POST pieprasījumi ar šiem parametriem:

MSSID: SMS ID, kāds tika saņemts no SendOne vai AddBatchRecipients komandām.
DLR: piegādes statuss ar vienu no šīm vērtībām:
- Delivered: SMS piegādāta.
- Sent: SMS nosūtīta, bet nav zināms vai saņemta (vārteja nav nodevusi DLR).
- Buffered: SMS nodota piegādei, bet stāv rindā.
- Undelivered: SMS nav izdevies piegādāt.
- Error: sistēmas vai vārtejas kļūda.
- Other: cita, neatpazīta piegādes atskaite. Error un Other statusiem normālos apstākļos nevajadzētu atgadīties vispār.
Expired (0/1): Ja īsziņa netika piegādāta (atskaitē parādās statuss Undelivered ), šis statuss precizēs to vai tas bija īsziņas noilguma iestāšanās dēļ (saņēmēja tālruņa numurs ir derīgs, bet īsziņas derīguma termiņa periodā nebija sasniedzams)
HMAC: Autentifikācijas kods ziņojumu pārbaudei.

Sīkāku informāciju par konkrēto piegādes statusu nozīmi varat atrast šeit: SMS piegādes statusu skaidrojums

Atskaites "webhook" pieprasījumu pārbaude

Lai pārliecinātos, ka šie "webhook" pieprasījumi ir autentiski, iespējams pārbaudīt IP adresi, lai redzētu, vai tā sakrīt ar vienu no mūsējām, taču papildus tam, tagad šie pieprasījumi satur arī autentifikācijas kodu, kuru iespējams izmantot atskaites pārbaudei.
Šis pārbaudes kods, pazīstams kā HMAC, tiek aprēķināts izmantojot SHA-256 jaucējfunkciju (hash function) un tā saturā ir 64 heksadecimālu rakstzīmju virkne.
Vērtība tiek iegūta no klienta API atslēgas, ziņojuma indentifikatora (MSSID) and piegādes atskaites vērtības (DLR):

HMAC = SHA-256( API ATSLĒGA + SHA-256( API ATSLĒGA + MSSID + DLR ) )

Ja saņemtā vērtība sakrīt ar to, ko varat aprēķināt savā pusē, saņemot pieprasījumu, varat būt pietiekami pārliecināts, ka dati nav izmainīti.

PHP piemērs HMAC vērtības aprēķināšanai saņemot pieprasījumu

// Pieņemot, ka $_POST vērtības ir aizpildītas pareizi, pārbaudes kods nav iekļauts. 
$api_key = 'YOURAPIKEYHERE';
$hmac = hash('sha256', $api_key.hash('sha256', $api_key.$_POST['MSSID'].$_POST['DLR']));

if ($hmac == $_POST['HMAC']) {
    // Pieprasījums ir derīgs 
}

Atjaunināts: 08/06/2021