Webhooks

Webhooks praneša jūsų sistemai apie SMS įvykius realiu laiku. Kai įvyksta įvykis, mes siunčiame HTTP POST užklausą į jūsų sukonfigūruotą endpoint su JSON duomenimis, aprašančiais įvykį.

Palaikomi įvykiai

Įvykio tipas	Aprašymas
SMS pristatymo patvirtinimas	Suaktyvinamas, kai pasikeičia išsiųsto SMS pristatymo būsena (pristatyta, nepavyko, pasibaigė galiojimas ir kt.)
Gautas SMS	Suaktyvinamas, kai SMS gaunamas į jūsų dedikuotą virtualų numerį

Konfigūracija

Norėdami konfigūruoti webhooks, eikite į Nustatymai → Webhooks savo darbo erdvėje ir pridėkite savo endpoint URL. Galite:

• Įjungti konkrečius įvykių tipus kiekvienam endpoint
• Pridėti pasirenkamą slaptąjį raktą HMAC parašo validavimui
• Pridėti aprašymą, padedantį identifikuoti endpoint

Tip

Rekomenduojame naudoti unikalų slaptąjį raktą kiekvienam webhook endpoint, kad patvirtintumėte gaunamų užklausų autentiškumą.

---

Webhook formatas

Visi webhooks siunčiami kaip HTTP POST užklausos su JSON turiniu, įvyniotų į standartinį voką.

Voko struktūra

JSON duomenys

id

required

string

Unikalus šio webhook įvykio identifikatorius.

timestamp

required

string

format: date-time (ISO 8601)

Kada įvyko įvykis.

workspaceId

required

string

Su šiuo įvykiu susieta darbo erdvės ID.

eventType

required

integer

Įvykio tipas: 1 - SMS pristatymo patvirtinimas, 2 - Gautas SMS.

data

required

object

Įvykio specifinis turinys (žr. žemiau).

Voko pavyzdys

{
  "id": "evt_abc123",
  "timestamp": "2025-01-15T10:30:00Z",
  "workspaceId": "ws_xyz789",
  "eventType": 1,
  "data": {
    // Įvykio specifinis turinys
  }
}

---

SMS pristatymo patvirtinimas

Siunčiamas, kai pasikeičia išsiųsto SMS pristatymo būsena. Naudokite tai stebėti, ar žinutės buvo sėkmingai pristatytos gavėjams.

Turinys

data objektas

messageId

required

string

Unikalus SMS žinutės identifikatorius.

clientReference

string

Jūsų pasirinktinė nuoroda, jei buvo pateikta siunčiant SMS.

deliveryStatus

required

string

Dabartinė žinutės pristatymo būsena.

errorCode

string

Klaidos kodas, jei žinutė nepavyko (žr. klaidos kodus žemiau).

processedAt

string

format: date-time (ISO 8601)

Kada žinutė buvo apdorota operatoriaus.

deliveredAt

string

format: date-time (ISO 8601)

Kada žinutė buvo pristatyta gavėjui.

Turinio pavyzdys

{
  "id": "evt_dr_123456",
  "timestamp": "2025-01-15T10:30:00Z",
  "workspaceId": "ws_xyz789",
  "eventType": 1,
  "data": {
    "messageId": "12345678",
    "clientReference": "uzsakymo-patvirtinimas-456",
    "deliveryStatus": "Delivered",
    "errorCode": null,
    "processedAt": "2025-01-15T10:29:55Z",
    "deliveredAt": "2025-01-15T10:30:00Z"
  }
}

Pristatymo būsenos reikšmės

Būsena	Galutinė	Aprašymas
Queued	Ne	Žinutė laukia siuntimo eilėje
Dispatched	Ne	Žinutė išsiųsta operatoriui
Delivered	Taip	Žinutė sėkmingai pristatyta gavėjui
Failed	Taip	Žinutės pristatymas visam laikui nepavyko
Expired	Taip	Žinutės galiojimas pasibaigė prieš pristatymą (operatoriaus laikas baigėsi)
Rejected	Taip	Žinutė atmesta operatoriaus
Cancelled	Taip	Žinutė atšaukta prieš pristatymą
Deleted	Taip	Žinutė ištrinta
Unknown	Ne	Būsena negalėjo būti nustatyta

Note

Galutinės būsenos reiškia, kad daugiau atnaujinimų šiai žinutei nebus siunčiama.

Klaidos kodai

Kai deliveryStatus yra Failed arba Rejected, errorCode laukas pateikia papildomą informaciją.

Kodas	Pavadinimas	Aprašymas
400	Queued	Žinutė vis dar eilėje
401	Dispatched	Žinutė išsiųsta
402	MessageUnroutable	Nėra maršruto šiam tikslui
403	InternalError	Įvyko vidinė klaida
404	TemporaryDeliveryFailure	Laikina pristatymo klaida - gali kartoti
405	UnmatchedParameter	Netinkamas parametras užklausoje
406	InternalExpiry	Žinutės galiojimas pasibaigė viduje
407	Cancelled	Žinutė atšaukta
408	InternalReject	Žinutė atmesta viduje
410	UnmatchedDefaultOriginator	Siuntėjo ID netinkamas šiam tikslui
411	ExceededPartsLimit	Žinutė viršijo maksimalų dalių limitą
412	UnprovisionedRegion	Tikslo regionas nepalaikomas
413	Blocked	Žinutė užblokuota operatoriaus arba filtro

---

Gautas SMS

Siunčiamas, kai SMS gaunamas į jūsų dedikuotą virtualų numerį. Tai leidžia gauti atsakymus ir įgyvendinti dvipusę SMS komunikaciją.

Caution

Gaunamų SMS webhooks reikalauja dedikuoto virtualaus numerio, priskirto jūsų darbo erdvei. Kreipkitės į palaikymo tarnybą dėl gaunamo numerio suteikimo.

Turinys

data objektas

messageId

required

string

Unikalus gautos žinutės identifikatorius.

inboundNumber

required

string

format: E.164

Jūsų virtualus numeris, kuris gavo žinutę.

sender

required

string

format: E.164

Telefono numeris, kuris išsiuntė žinutę.

body

required

string

Gautos žinutės turinys.

receivedAt

required

string

format: date-time (ISO 8601)

Kada žinutė buvo gauta.

Turinio pavyzdys

{
  "id": "evt_in_789012",
  "timestamp": "2025-01-15T14:22:30Z",
  "workspaceId": "ws_xyz789",
  "eventType": 2,
  "data": {
    "messageId": "inb_987654",
    "inboundNumber": "+447700900100",
    "sender": "+447700900123",
    "body": "Taip, prašau patvirtinti mano susitikimą",
    "receivedAt": "2025-01-15T14:22:30Z"
  }
}

---

Saugumas

HMAC parašo validavimas

Jei konfigūruojate slaptąjį raktą savo webhook endpoint, mes įtraukiame HMAC-SHA256 parašą, kurį turėtumėte validuoti, kad įsitikintumėte užklausos autentiškumu.

Antraštės

Antraštė	Aprašymas
X-Webhook-Signature	Base64 koduotas HMAC-SHA256 parašas
X-Webhook-Timestamp	Unix laiko žymė (sekundėmis), kada webhook buvo išsiųstas

Parašo skaičiavimas

Parašas skaičiuojamas taip:

HMAC-SHA256(secret, timestamp + "." + payload)

Kur:

• secret yra jūsų sukonfigūruotas webhook slaptasis raktas
• timestamp yra reikšmė iš X-Webhook-Timestamp
• payload yra neapdorotas JSON užklausos turinys

Validavimo pavyzdys

.NET

using System.Security.Cryptography;
using System.Text;

public bool ValidateWebhookSignature(
    string payload,
    string signature,
    string timestamp,
    string secret)
{
    var signatureData = $"{timestamp}.{payload}";
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(signatureData));
    var expectedSignature = Convert.ToBase64String(hash);

    return signature == expectedSignature;
}

Node.js

const crypto = require('crypto');

function validateWebhookSignature(payload, signature, timestamp, secret) {
    const signatureData = `${timestamp}.${payload}`;
    const expectedSignature = crypto
        .createHmac('sha256', secret)
        .update(signatureData)
        .digest('base64');

    return signature === expectedSignature;
}

PHP

function validateWebhookSignature($payload, $signature, $timestamp, $secret) {
    $signatureData = $timestamp . '.' . $payload;
    $expectedSignature = base64_encode(
        hash_hmac('sha256', $signatureData, $secret, true)
    );

    return hash_equals($signature, $expectedSignature);
}

Tip

Visada naudokite pastovaus laiko palyginimą (kaip hash_equals PHP) laiko atakų prevencijai validuojant parašus.

---

Pakartojimo elgsena

Jei jūsų endpoint grąžina ne-2xx atsakymą arba baigiasi laikas, mes pakartosime pristatymą su eksponentiniu atidėjimu:

Bandymas	Atidėjimas
1	Nedelsiant
2	5 minutės
3	15 minučių
4	1 valanda
5	4 valandos
6	8 valandos
7	12 valandų

Po 5 nuoseklių nesėkmių, webhook endpoint automatiškai išjungiamas, kad būtų išvengta tolesnių nesėkmingų pristatymų. Galite jį vėl įjungti iš webhook nustatymų puslapio, kai jūsų endpoint bus sveikas.

Caution

Užtikrinkite, kad jūsų webhook endpoint atsakytų per 45 sekundes. Užklausos, viršijančios šį laiką, bus laikomos nesėkmėmis.

---

Geriausios praktikos

1. Atsakykite greitai - Grąžinkite 2xx atsakymą kuo greičiau. Apdorokite webhook duomenis asinchroniškai, jei reikia.

2. Tvarkykite dublikatus - Retais atvejais galite gauti tą patį webhook daugiau nei kartą. Naudokite id lauką dublikatų pašalinimui.

3. Validuokite parašus - Visada validuokite HMAC parašą, kai sukonfigūruotas slaptasis raktas, kad užtikrintumėte užklausų autentiškumą.

4. Naudokite HTTPS - Visada naudokite HTTPS endpoints, kad webhook duomenys būtų užšifruoti perdavimo metu.

5. Stebėkite nesėkmes - Reguliariai tikrinkite savo webhook nustatymus, kad įsitikintumėte, jog endpoints nebuvo automatiškai išjungti dėl nesėkmių.