Webhoki w czasie rzeczywistym — raporty dostawy, odpowiedzi, skrzynka odbiorcza, opt-outy i więcej.

Czym są webhooks?

Webhooki są rozszerzeniem interfejsu API, ale zamiast twój kod żądać danych od Smstools, Smstools wysyła dane do ciebie. Dane przychodzą w żądaniu sieciowym do twojej aplikacji. Webhooki są również używane do powiadamiania twojej aplikacji o zdarzeniach, takich jak przychodzące połączenie lub wiadomość. Ponieważ serwery Smstools muszą być w stanie wysyłać dane do twojej aplikacji za pomocą webhooków, musisz skonfigurować serwer sieciowy, aby otrzymywać przychodzące żądania HTTP. Musisz również określić URL każdego webhooka na swoim serwerze sieciowym, aby dane mogły być wysyłane do każdego.

REJESTRACJA →

Dostarczanie w czasie rzeczywistym
Bezpieczny endpoint

POST POST → twój endpoint

{  "webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",  "webhook_type": "delivery_report",  "username": "myusername",  "timezone": "Europe/Brussels",  "method": "POST",  "created": "2026-01-01 09:00:06",  "created_utc": "2026-01-01 08:00:06",  "message": {    "messageid": "e1qk89exbzgf6fzfunceym2sd67h88",    "datetime": "2026-01-01 09:00:00",    "content": "here comes your message body",    "sender": "yoursender",    "receiver": "32470123456",    "reference": "yourref",    "message_type": "sms",    "delivery_code": "1",    "delivery_status": "delivered",    "delivery_status_datetime": "2026-01-01 09:00:05",    "cost": 1,    "cost_type": "credits"  }}

Przykładowy payload

Wsparcie UE

Zgodny z RODO

Serwery UE · 99,97% uptime

Push w czasie rzeczywistym

Typ	Opis
delivery_report	Raport dostarczenia po każdej wysłanej wiadomości. Czasami może być 2 webhooki: najpierw status „przesłano”, a później status „dostarczono” lub „nie dostarczono”. Czasami dostępne są dodatkowe szczegóły, gdy wiadomość nie została dostarczona.
read_report	Potwierdzenie odczytu po przeczytaniu wiadomości. Potwierdzenie odczytu jest dostępne tylko dla Wiadomości społecznych lub poprzez użycie linku „Poproś o raport odczytu”.
inbox_message	Wiadomość przychodząca. Dostępne tylko w przypadku korzystania z Wiadomości społecznych lub numeru wirtualnego.
call_forwarding	Przekierowanie połączeń. Dostępne tylko, jeśli korzystasz z Social Messaging lub wirtualnego numeru.
add_contact	1 kontakt został dodany za pomocą API lub oprogramowania
delete_contact	1 kontakt został usunięty za pomocą API lub oprogramowania
add_group	Grupa została dodana za pomocą API lub oprogramowania
delete_group	Grupa została usunięta za pomocą API lub oprogramowania
add_optout	Kontakt został dodany do listy opt-out za pomocą API lub oprogramowania
delete_optout	Kontakt został usunięty z listy opt-out za pomocą API lub oprogramowania
funds_purchased	Konto zrealizowało nowe zamówienie na środki
insufficient_funds	Konto nie ma już dostępnych środków
email2sms_received	Email2Sms otrzymał e-mail i próbował wysłać go przez SMS
api_error	Żądanie API nie powiodło się. Zawiera komunikat błędu, kod błędu oraz status HTTP nieudanego żądania.

Code	Status	Wyjaśnienie
0	SUBMITTED	Ta wiadomość została dostarczona przez operatora, ale nie otrzymaliśmy raportu dostarczenia.
1	DELIVERED	Ta wiadomość została pomyślnie dostarczona.
2	NOT DELIVERED	Ta wiadomość nie została dostarczona. Możliwy powód: odbiorca znajduje się poza zasięgiem sieci, problemy z siecią, odbiorca za granicą.
3	BUFFERED	Ta wiadomość została dostarczona przez operatora, ale nie do odbiorcy.
4	REJECTED	Ta wiadomość została odrzucona przez operatora.
5	REJECTED	Szczegóły poniżej!
9	UNKNOWN	Brak dostępnych raportów dostarczenia dla tej wiadomości.

Poniżej przegląd możliwych kodów błędów, które możesz otrzymać.

Status	Wyjaśnienie
10	Numer odbiorcy jest nieprawidłowy lub nieznany
11	Odbiorca tymczasowo znajduje się poza zasięgiem operatora sieciowego
12	Problem związany z telefonem.
13	Problem z siecią operatora
14	Wiadomość wygasła - powód nieznany
15	Odbiorca figuruje na czarnej liście
16	Problem z treścią wiadomości
17	Odbiorca nie może zostać uregulowany
18	Operator odrzucił to z powodu spamu
19	Abonent nie może odbierać wiadomości premium (zablokowane przez operatora)

Status	Wyjaśnienie
2000	INSUFFICIENT_FUNDS
2001	TOO_LONG
2002	TOO_SHORT
2003	TIMEOUT
2004	GATEWAY_ISSUES
2005	INVALID_SENDER
2006	INVALID_NUMBER
4000	UNKNOWN
4001	EMPTY_MESSAGE
4002	EMPTY_CLIENT
4003	LOCKED
4004	BLOCKED
4005	JOB_FAILED
4006	DUPLICATE
4007	INVALID_CONTENT

Jeśli dla adresu URL webhooka ustawiono sekret podpisu, każde żądanie webhooka zawiera nagłówki X-Smstools-Timestamp (znacznik czasu Unix) oraz X-Smstools-Signature (format: t={timestamp},v1={signature}).

Aby zweryfikować podpis: połącz znacznik czasu, kropkę (.) i surowe ciało JSON żądania, oblicz HMAC SHA-256 tego ciągu przy użyciu sekretu podpisu i porównaj wynik z wartością v1. W przypadku webhooków GET podpisywany jest query string zamiast ciała JSON.

POST /your/webhook/endpoint HTTP/1.1
Content-Type: application/json
X-Smstools-Timestamp: 1767254406
X-Smstools-Signature: t=1767254406,v1=20bb9bf973ab6471e64f88a73fa11926c882dba87234f6760b87b5cbb0bf5aaa

$signedPayload = $timestamp . "." . $rawBody;
$signature = hash_hmac("sha256", $signedPayload, $secret);
hash_equals($signature, $v1);

Przegląd dostępnych webhooków

Przykład: raport dostarczenia

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "delivery_report",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:00:06",
	"created_utc": "2026-01-01 08:00:06",
	"message": {
	  "messageid": "e1qk89exbzgf6fzfunceym2sd67h88",
	  "datetime": "2026-01-01 09:00:00",
	  "content": "here comes your message body",
	  "sender": "yoursender",
	  "receiver": "32470123456",
	  "reference": "yourref",
	  "message_type": "sms",
	  "delivery_code": "1",
	  "delivery_status": "delivered",
	  "delivery_status_datetime": "2026-01-01 09:00:05",
	  "cost": 1,
	  "cost_type": "credits"
	}
}

Dodatkowe szczegóły w przypadku wiadomości NIEDOSTARCZONEJ (Code 2)

								{
	"webhook_id": "wh_b1c67831-8bed-4d89-b15e-73632e2e4c10",
	"webhook_type": "delivery_report",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:00:15",
	"created_utc": "2026-01-01 08:00:15",
	"message": {
	  "messageid": "f2rl90fycahg7gagvodfzn3te78i99",
	  "datetime": "2026-01-01 09:00:00",
	  "content": "here comes your message body",
	  "sender": "yoursender",
	  "receiver": "32470123456",
	  "reference": "yourref",
	  "message_type": "sms",
	  "delivery_code": "2",
	  "delivery_status": "not delivered",
	  "delivery_status_datetime": "2026-01-01 09:00:12",
	  "delivery_code_detail": "10",
	  "delivery_code_detail_description": "Unknown Subscriber",
	  "cost": 1,
	  "cost_type": "credits"
	}
}

Dodatkowe pola w przypadku odpowiedzi lub potwierdzenia odczytu

								{
	"webhook_id": "wh_c2d78942-9cfe-4e9a-8c26-84743f3f5d21",
	"webhook_type": "delivery_report",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:02:35",
	"created_utc": "2026-01-01 08:02:35",
	"message": {
	  "messageid": "e1qk89exbzgf6fzfunceym2sd67h88",
	  "datetime": "2026-01-01 09:00:00",
	  "content": "here comes your message body",
	  "sender": "yoursender",
	  "receiver": "32470123456",
	  "reference": "yourref",
	  "message_type": "sms",
	  "delivery_code": "1",
	  "delivery_status": "delivered",
	  "delivery_status_datetime": "2026-01-01 09:00:05",
	  "confirm_type": "replies_yes_no_answer",
	  "confirm_date": "2026-01-01 09:02:30",
	  "confirm_memo": "YES",
	  "cost": 1,
	  "cost_type": "credits"
	}
}

Przykład: raport potwierdzenia odczytu

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "read_report",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:01:01",
	"created_utc": "2026-01-01 08:01:01",
	"message": {
	  "messageid": "e1qk89exbzgf6fzfunceym2sd67h88",
	  "datetime": "2026-01-01 09:00:00",
	  "content": "here comes your message body",
	  "sender": "yoursender",
	  "receiver": "32470123456",
	  "reference": "yourref",
	  "message_type": "sms",
	  "delivery_code": "1",
	  "delivery_status": "delivered",
	  "delivery_status_datetime": "2026-01-01 09:00:05",
	  "read_status": "message_read",
	  "read_datetime": "2026-01-01 09:01:00"
	}
}

Przykład: wiadomość przychodząca

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "inbox_message",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:05:01",
	"created_utc": "2026-01-01 08:05:01",
	"message": {
	  "id": "12345678",
	  "public_id": "inb_46f4c0e37652d4149352e1cb54fed50b",
	  "date": "2026-01-01 09:05:00",
	  "date_iso8601": "2026-01-01T09:05:00+01:00",
	  "date_utc": "2026-01-01 08:05:00",
	  "date_utc_iso8601": "2026-01-01T08:05:00+00:00",
	  "sender": "sendernumber",
	  "receiver": "12345678",
	  "content": "message content",
	  "type": "sms",
	  "file": null,
	  "processed": 0
	},
	"isreply": {
	  "reply": true,
	  "orig_message_content": "original message content",
	  "orig_messageid": "985zvqipp73csuuha2079fbshx",
	  "orig_messagedate": "2026-01-01 09:00:00",
	  "orig_messagedate_iso8601": "2026-01-01T09:00:00+01:00",
	  "orig_messagedate_utc": "2026-01-01 08:00:00",
	  "orig_messagedate_utc_iso8601": "2026-01-01T08:00:00+00:00",
	  "orig_sender": "32471123456",
	  "orig_receiver": "12345678",
	  "orig_reference": ""
	}
}

Przykład: przekierowanie połączeń

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "call_forwarding",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:10:01",
	"created_utc": "2026-01-01 08:10:01",
	"message": {
	  "id": "12345678",
	  "public_id": "inb_7ecad8b1a486b73732b897fde12f080c",
	  "date": "2026-01-01 09:10:00",
	  "date_iso8601": "2026-01-01T09:10:00+01:00",
	  "date_utc": "2026-01-01 08:10:00",
	  "date_utc_iso8601": "2026-01-01T08:10:00+00:00",
	  "sender": "sendernumber",
	  "receiver": "12345678",
	  "content": "Incoming VOIP Call - Forwarded to XXXXX",
	  "content_type": "complete",
	  "type": "call"
	}
}

Przykład: Dodaj kontakt

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "add_contact",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:15:00",
	"created_utc": "2026-01-01 08:15:00",
	"contact": {
	  "action": "add",
	  "groupid": "12345",
	  "groupname": "Groupname",
	  "receiver": "32498123456",
	  "firstname": "John",
	  "lastname": "Doe",
	  "Custom1": null,
	  "Custom2": null,
	  "Custom3": null,
	  "Custom4": null,
	  "Custom5": null,
	  "Custom6": null,
	  "Custom7": null,
	  "Custom8": null,
	  "unsubscribed": false,
	  "unsubscribe_date": null
	}
}

Przykład: Usuń kontakt

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "delete_contact",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:16:00",
	"created_utc": "2026-01-01 08:16:00",
	"contact": {
	  "action": "delete",
	  "groupid": "12345",
	  "groupname": "Groupname",
	  "receiver": "32498123456",
	  "firstname": "John",
	  "lastname": "Doe",
	  "Custom1": null,
	  "Custom2": null,
	  "Custom3": null,
	  "Custom4": null,
	  "Custom5": null,
	  "Custom6": null,
	  "Custom7": null,
	  "Custom8": null,
	  "unsubscribed": false,
	  "unsubscribe_date": null
	}
}

Przykład: Dodaj grupę

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "add_group",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:20:00",
	"created_utc": "2026-01-01 08:20:00",
	"group": {
	  "action": "add",
	  "groupid": "12345",
	  "groupname": "Groupname"
	}
}

Przykład: Usuń grupę

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "delete_group",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:21:00",
	"created_utc": "2026-01-01 08:21:00",
	"group": {
	  "action": "delete",
	  "groupid": "12345",
	  "groupname": "Groupname"
	}
}

Przykład: Dodaj opt-out

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "add_optout",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2025-08-04 14:30:00",
	"created_utc": "2025-08-04 12:30:00",
	"optout": {
	  "action": "add",
	  "id": "1234",
	  "number": "32498123456",
	  "memo": "Sample opt-out",
	  "date": "2025-08-04",
	  "date_utc": "2025-08-04"
	}
}

Przykład: Usuń opt-out

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "delete_optout",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2025-08-04 14:31:00",
	"created_utc": "2025-08-04 12:31:00",
	"optout": {
	  "action": "delete",
	  "number": "32498123456",
	  "date": "2025-08-04",
	  "date_utc": "2025-08-04"
	}
}

Przykład: Zakupione środki

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "funds_purchased",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2025-08-04 14:33:50",
	"created_utc": "2025-08-04 12:33:50",
	"funds": {
	  "order_id": "1234",
	  "item_amount": 1,
	  "currency": "eur",
	  "total_price": 10,
	  "price_excl": 0,
	  "purchase_type": "credits",
	  "payment_mode": "online",
	  "reference": "Reference",
	  "date": "2025-08-04 14:33:45",
	  "date_utc": "2025-08-04 12:33:45"
	}
}

Przykład: Niewystarczające środki

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "insufficient_funds",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2025-08-04 14:34:22",
	"created_utc": "2025-08-04 12:34:22",
	"funds": {
	  "item_amount": "0.000",
	  "item_type": "balance",
	  "message": "Insufficient funds",
	  "date": "2025-08-04 14:34:22",
	  "date_utc": "2025-08-04 12:34:22"
	}
}

Przykład: Wyzwalacz Email2SMS

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "email2sms_received",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2025-01-01 10:00:02",
	"created_utc": "2025-01-01 09:00:02",
	"email2sms": {
	  "sender": "[email protected]",
	  "receiver": {
		"group": false,
		"receiver": "32498123456"
	  },
	  "result": "Success",
	  "status": "Message Sent",
	  "email_message_id": "abc123def456",
	  "sms_message_id": "985zvqipp73csuuha2079fbshx",
	  "date": "2025-01-01 10:00:00",
	  "date_utc": "2025-01-01 09:00:00"
	}
}

Przykład: błąd API

								{
	"webhook_id": "wh_a9b56720-7adc-4c78-a04d-62521d1d3b09",
	"webhook_type": "api_error",
	"username": "myusername",
	"timezone": "Europe/Brussels",
	"method": "POST",
	"created": "2026-01-01 09:25:00",
	"created_utc": "2026-01-01 08:25:00",
	"error": {
	  "error": "Destination number 32498123456 missing or invalid",
	  "error_code": 103,
	  "sender": "yoursender",
	  "receiver": "32498123456",
	  "http_code": 400,
	  "date": "2026-01-01 09:25:00",
	  "date_utc": "2026-01-01 08:25:00"
	}
}

Odkryj naszą platformę SMS już dziś!

Wysyłanie SMS-ów nigdy nie było tak proste.

REJESTRACJA → Kontakt

Czym są webhooks?

Przegląd dostępnych webhooków

Statusy raportów dostarczenia (Webhook type 'delivery_report')

Dodatkowe szczegóły w przypadku wiadomości NIEDOSTARCZONEJ (Code 2)

Dodatkowe szczegóły w przypadku wiadomości ODRZUCONEJ (Code 5)

Podpisywanie webhooków

Przegląd dostępnych webhooków

Przykład: raport dostarczenia

Dodatkowe szczegóły w przypadku wiadomości NIEDOSTARCZONEJ (Code 2)

Dodatkowe pola w przypadku odpowiedzi lub potwierdzenia odczytu

Przykład: raport potwierdzenia odczytu

Przykład: wiadomość przychodząca

Przykład: przekierowanie połączeń

Przykład: Dodaj kontakt

Przykład: Usuń kontakt

Przykład: Dodaj grupę

Przykład: Usuń grupę

Przykład: Dodaj opt-out

Przykład: Usuń opt-out

Przykład: Zakupione środki

Przykład: Niewystarczające środki

Przykład: Wyzwalacz Email2SMS

Przykład: błąd API

Wysyłanie SMS-ów nigdy nie było tak proste.