Webhook

Webhook inatuma matukio kwenye seva yako yanapotokea, kwa hiyo huhitaji kuuliza tena na tena. Webhook moja ni ya ufunguo mmoja wa API. Inapokea matukio ya nambari zilizonunuliwa kwa ufunguo huo, pamoja na tahadhari za salio la chini kwa akaunti yako.

Matukio

Kutengeneza webhook

Kwenye Akaunti > Wasanidi, fungua ufunguo na uongeze webhook yenye URL, matukio unayoyataka na maelezo ya hiari. Kila ufunguo unaweza kuwa na hadi webhook 3.

URL lazima:

• ianze na https://;
• itumie jina la seva, si anwani ya IP;
• ielekee anwani ya umma. Mitandao binafsi, localhost na masafa kama hayo yanakataliwa.

Unapokea siri ya kutia sahihi inayoanza na whsec_. Kama ufunguo wa API, inaonyeshwa mara moja tu. Unaweza kuibadilisha baadaye, na hilo pia linaomba nenosiri.

Muundo wa utumaji

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: SmsGrab-Webhooks/1.0
SmsGrab-Event: activation.code_received
SmsGrab-Delivery: 9f7d6c1e-2b44-4c1a-8f0e-6a3d2c1b0e9f
SmsGrab-Signature: t=1790503200,v1=3b9a0c…

{ "id": "evt_4e1f…", "type": "activation.code_received", "created_at": "2026-09-27T10:06:12.004Z",
  "api_version": "2026-09-27", "data": { "activation": { "id": "5c1d0c2e-…", "status": "CODE_RECEIVED" } } }

Thibitisha sahihi

SmsGrab-Signature ina muhuri wa muda t na v1, ambayo ni HMAC-SHA256 ya t, nukta na mwili ghafi wa ombi, huku siri yako ikiwa ufunguo. Kataa utumaji ambao muhuri wake wa muda unatofautiana na saa yako kwa zaidi ya sekunde 300, na ulinganishe sahihi kwa muda usiobadilika.

[$t, $v1] = (function (string $h): array {
    parse_str(str_replace(',', '&', $h), $p);
    return [(int) ($p['t'] ?? 0), (string) ($p['v1'] ?? '')];
})($_SERVER['HTTP_SMSGRAB_SIGNATURE'] ?? '');
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $t.'.'.$body, getenv('SMSGRAB_WEBHOOK_SECRET'));
$ok = abs(time() - $t) <= 300 && hash_equals($expected, $v1);

import hmac, hashlib, time

def verify(header: str, body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return abs(time.time() - t) <= 300 and hmac.compare_digest(expected, parts.get("v1", ""))

import crypto from 'node:crypto';

export function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t ?? 0);
  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
  const given = Buffer.from(parts.v1 ?? '', 'utf8');
  return Math.abs(Date.now() / 1000 - t) <= 300 && given.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(expected, 'utf8'), given);
}

Kagua kila mara mwili ghafi kama ulivyoupokea hasa, kabla ya kuchanganua JSON.

Jibu haraka

Jibu kwa hali yoyote ya 2xx ndani ya sekunde 10 na ufanye kazi ya polepole baadaye, kwa mfano kwenye foleni. Uelekezaji upya haufuatwi.

Majaribio ya kurudia

Utumaji ulioshindwa unarudiwa baada ya dakika 1, dakika 5, dakika 15, saa 1, saa 3, saa 6, saa 12 na saa 24. Majaribio ya kurudia yanabeba id ileile ya tukio, kwa hiyo hifadhi vitambulisho ulivyoshughulikia na uruke nakala. Matukio ya uanzishaji mmoja yanafika kwa mpangilio.

Kuzimwa kiotomatiki

• Kujibu 410 Gone kunazima webhook mara moja.
• Baada ya majaribio 50 mfululizo yaliyoshindwa katika angalau saa 24, webhook inazimwa na unapokea arifa. Rekebisha endpoint yako, kisha uwashe webhook tena.
• Kubatilisha ufunguo kunazima webhook zake.

Jaribu na utume tena

Tuma tukio la webhook.test kutoka kwenye ukurasa wa webhook ili uone mara moja msimbo wa hali, muda wa kujibu na hitilafu yoyote. Orodha ya utumaji inahifadhi kila utumaji kwa siku 30, na unaweza kutuma tena wowote.