# Gelen SMS webhook'u kaydetme > Hesaba gelen SMS'lerin gönderileceği adres. - **İstek:** `POST https://ext-api.netgsm.com.tr/sms/v3/webhooks/inbox` - **Canlı ortam:** `https://ext-api.netgsm.com.tr/sms/v3` - **Kimlik doğrulama:** `Authorization: Bearer ` - **HTML sayfası:** https://api-docs.netgsm.com.tr/register-inbox-webhook/ - **OpenAPI tanımı:** https://api-docs.netgsm.com.tr/openapi/sms-v3.yaml (operationId: `registerInboxWebhook`) ## Açıklama Hesaba gelen SMS'lerin gönderileceği adres. Hesap başına bir tane; var olanın üzerine kayıt 409 ile reddedilir; önce mevcut kaydı silmeniz gerekir. Etkinleştirme gerekmez; alt kullanıcı için SMS menüsü gerekir. ## İstek ### Gövde (`application/json`, zorunlu) - `url` (string, zorunlu, en fazla uzunluk 1024): Host'u yalnızca genel (public) adreslere çözümlenen mutlak bir http ya da https URL - loopback, özel, link-local ya da başka bir şekilde iç adres olamaz. Port verilirse 1 ile 65535 arasındadır. - `headers` (string, isteğe bağlı, en fazla uzunluk 500): Webhook adresinizin Netgsm'den beklediği başlık; örneğin adresiniz bir kimlik doğrulama bilgisi istiyorsa "Authorization: Bearer ". Netgsm bu başlığı adresinize yaptığı her istekte aynen gönderir; böylece isteğin Netgsm'den geldiğini doğrulayabilirsiniz. Tek bir satır, `Name: value` biçiminde; yalnızca yazdırılabilir ASCII, satır sonu olmadan. Değer virgül (,) ya da iki nokta üst üste (:) içeremez. İsteğe bağlı; boş bırakılırsa ek başlık gönderilmez. Örnek gövde: ```json { "url": "https://example.com/inbox", "headers": "Authorization: Bearer token123" } ``` ## Örnek istek ```bash curl -X POST 'https://ext-api.netgsm.com.tr/sms/v3/webhooks/inbox' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "url": "https://example.com/inbox", "headers": "Authorization: Bearer token123" }' ``` ## Yanıtlar ### 201 — Kaydedildi. Gövde (`application/json`): - `url` (string, zorunlu) - `headers` (string, null olabilir, zorunlu): Kayıtta verilen başlık satırı; verilmediyse `null`. - `registeredAt` (string, date-time, zorunlu): Webhook'un kaydedildiği zaman. Örnek (şemadan üretildi): ```json { "url": "string", "headers": "string", "registeredAt": "2026-01-01T10:00:00+03:00" } ``` ### 400 — INVALID_REQUEST. `url` eksik, çok uzun ya da host içeren mutlak bir http(s) URL değil; host'u çözümlenmiyor ya da yalnızca genel (public) adreslere çözümlenmiyor; `headers` çok uzun, tek bir `Name: value` satırı değil ya da değerinde virgül veya iki nokta üst üste var; gövde JSON değil. Gövde (`application/json`): - `code` (string, zorunlu): Değerler: `INVALID_REQUEST`. - `message` (string, zorunlu): Okunabilir ayrıntı. `UNAUTHENTICATED` için `no bearer token` ya da `invalid or expired token`. `REJECTED_HEADER` için ret adıdır; yalnızca rakamlardan oluşan bir göndericide ` (subscriber number headers were not offered)` ekini taşıyabilir. `RATE_LIMITED` için sınırı belirtir; `FORBIDDEN` ve `REJECTED_IYS` için sabit bir cümledir. `SERVICE_UNAVAILABLE` ve `INTERNAL_ERROR` genel bir cümle taşır; bildirirken `requestId` değerini paylaşmanız gerekir. - `requestId` (string, zorunlu): İsteğe özgü kimlik, 32 onaltılık karakter. Bir sorun bildirirken bu değeri paylaşmanız, isteğin kayıtlarda bulunmasını sağlar. - `timestamp` (string, date-time, zorunlu) - `violations` (array, null olabilir, zorunlu): Yalnızca gövde doğrulamasından gelen INVALID_REQUEST için dolu, aksi halde `null`. - `violations[].field` (string, isteğe bağlı) - `violations[].message` (string, isteğe bağlı) - `rejectedItems` (array, isteğe bağlı, en fazla kayıt 100): Yalnızca `NO_DELIVERABLE_MESSAGES` yanıtında bulunur; diğer hatalarda alan hiç yer almaz. Reddedilen kayıtlar, `index` sırasıyla ilk 100 tanesi; 202 yanıtındaki `rejectedItems` ile aynıdır. - `rejectedItems[].index` (integer, zorunlu): Kaydın istekteki `messages` dizisindeki sırası, sıfırdan başlar. - `rejectedItems[].recipient` (string, null olabilir, zorunlu): Kayıttaki alıcı. Kayıt `null` ise ya da alıcısı yoksa `null`. - `rejectedItems[].reason` (string, zorunlu): Değerler: `INVALID_RECIPIENT`, `INVALID_MESSAGE`, `MESSAGE_TOO_LONG`, `MALFORMED_ENTRY`, `DUPLICATE_RECIPIENT`, `NO_INTERNATIONAL_PERMISSION`. | Değer | Ne zaman | |---|---| | `INVALID_RECIPIENT` | Numara eksik ya da biçimi yanlış; bkz. `recipient`. | | `INVALID_MESSAGE` | Metin eksik ya da boş. | | `MESSAGE_TOO_LONG` | Metin, `encoding` ve gönderici türüne göre sınırı aşıyor; bkz. `encoding`. | | `MALFORMED_ENTRY` | Kayıt `null`. | | `DUPLICATE_RECIPIENT` | Aynı alıcı istekte daha sonra yeniden geçiyor. Yalnızca son geçen kayıt gönderilir, öncekiler bu nedenle reddedilir; son kayıt başka bir nedenle reddedilse bile. Numaralar yazıldığı gibi karşılaştırılır. Mükerrer gönderime izin verilen hesaplarda uygulanmaz. | | `NO_INTERNATIONAL_PERMISSION` | Numara yurt dışı (`-` ile başlıyor) ve hesabın yurt dışı gönderim izni yok. İzin için destek ekibiyle iletişime geçmelisiniz. Yalnızca başka bir hatası olmayan kayıtlarda bildirilir. | Bir kayıt birden fazla nedenle hatalıysa tek neden bildirilir; öncelik: `DUPLICATE_RECIPIENT`, `MALFORMED_ENTRY`, `MESSAGE_TOO_LONG`, `INVALID_RECIPIENT`, `INVALID_MESSAGE`, `NO_INTERNATIONAL_PERMISSION`. - `rejectedItemsTruncated` (boolean, isteğe bağlı): Yalnızca `rejectedItems` ile birlikte bulunur. 100'den fazla kayıt reddedildiğinde true. Örnek (şemadan üretildi): ```json { "code": "INVALID_REQUEST", "message": "string", "requestId": "string", "timestamp": "2026-01-01T10:00:00+03:00", "violations": [ { "field": "string", "message": "string" } ], "rejectedItems": [ { "index": 0, "recipient": "string", "reason": "INVALID_RECIPIENT" } ], "rejectedItemsTruncated": true } ``` ### 401 — UNAUTHENTICATED. Bearer token yok ya da token geçersiz veya süresi dolmuş; `message` `no bearer token` ya da `invalid or expired token`. Gövde (`application/json`): alanlar 400 yanıtıyla aynı; farklı olanlar: - `code` (string, zorunlu): Değerler: `UNAUTHENTICATED`. Örnek (şemadan üretildi): ```json { "code": "UNAUTHENTICATED", "message": "string", "requestId": "string", "timestamp": "2026-01-01T10:00:00+03:00", "violations": [ { "field": "string", "message": "string" } ], "rejectedItems": [ { "index": 0, "recipient": "string", "reason": "INVALID_RECIPIENT" } ], "rejectedItemsTruncated": true } ``` ### 403 — FORBIDDEN. SMS menüsü olmayan bir alt kullanıcı. Gövde (`application/json`): alanlar 400 yanıtıyla aynı; farklı olanlar: - `code` (string, zorunlu): Değerler: `FORBIDDEN`. Örnek (şemadan üretildi): ```json { "code": "FORBIDDEN", "message": "string", "requestId": "string", "timestamp": "2026-01-01T10:00:00+03:00", "violations": [ { "field": "string", "message": "string" } ], "rejectedItems": [ { "index": 0, "recipient": "string", "reason": "INVALID_RECIPIENT" } ], "rejectedItemsTruncated": true } ``` ### 409 — ALREADY_EXISTS. Kayıtlı bir gelen SMS webhook'u var; önce silmeniz gerekir. Hesap için başka bir gelen SMS webhook kaydı sürerken de döner; o tamamlandığında istek yeniden gönderilebilir. Gövde (`application/json`): alanlar 400 yanıtıyla aynı; farklı olanlar: - `code` (string, zorunlu): Değerler: `ALREADY_EXISTS`. Örnek (şemadan üretildi): ```json { "code": "ALREADY_EXISTS", "message": "string", "requestId": "string", "timestamp": "2026-01-01T10:00:00+03:00", "violations": [ { "field": "string", "message": "string" } ], "rejectedItems": [ { "index": 0, "recipient": "string", "reason": "INVALID_RECIPIENT" } ], "rejectedItemsTruncated": true } ``` ### 429 — RATE_LIMITED. Hesap için bu uç noktanın sınırı aşıldı; `message` sınırı belirtir. `Retry-After` yalnızca hesabın gönderimi askıya alındığında bulunmaz. Başlıklar: - `Retry-After` (integer): İsteğin tekrarlanabileceği zamana kadar kalan tam saniye. Gövde (`application/json`): alanlar 400 yanıtıyla aynı; farklı olanlar: - `code` (string, zorunlu): Değerler: `RATE_LIMITED`. Örnek (şemadan üretildi): ```json { "code": "RATE_LIMITED", "message": "string", "requestId": "string", "timestamp": "2026-01-01T10:00:00+03:00", "violations": [ { "field": "string", "message": "string" } ], "rejectedItems": [ { "index": 0, "recipient": "string", "reason": "INVALID_RECIPIENT" } ], "rejectedItemsTruncated": true } ``` ### 500 — INTERNAL_ERROR, `message` `internal error`. Beklenmeyen hata; bildirirken `requestId` değerini paylaşmanız gerekir. Gövde (`application/json`): alanlar 400 yanıtıyla aynı; farklı olanlar: - `code` (string, zorunlu): Değerler: `INTERNAL_ERROR`. Örnek (şemadan üretildi): ```json { "code": "INTERNAL_ERROR", "message": "string", "requestId": "string", "timestamp": "2026-01-01T10:00:00+03:00", "violations": [ { "field": "string", "message": "string" } ], "rejectedItems": [ { "index": 0, "recipient": "string", "reason": "INVALID_RECIPIENT" } ], "rejectedItemsTruncated": true } ``` ### 503 — SERVICE_UNAVAILABLE. Hiçbir şey yapılmadı; yeniden denemek güvenlidir. Gövde (`application/json`): alanlar 400 yanıtıyla aynı; farklı olanlar: - `code` (string, zorunlu): Değerler: `SERVICE_UNAVAILABLE`. Örnek (şemadan üretildi): ```json { "code": "SERVICE_UNAVAILABLE", "message": "string", "requestId": "string", "timestamp": "2026-01-01T10:00:00+03:00", "violations": [ { "field": "string", "message": "string" } ], "rejectedItems": [ { "index": 0, "recipient": "string", "reason": "INVALID_RECIPIENT" } ], "rejectedItemsTruncated": true } ``` ## Geri çağrılar (webhook) ### inboundSms: `POST {$request.body#/url}` Gelen SMS webhook adresinize gönderilir Hesaba gelen her SMS, geldiği anda kayıtlı adrese tek tek `POST` ile gönderilir. - Kayıt sırasında `headers` verildiyse o başlık her istekte gönderilir; isteğin Netgsm'den geldiğini bu başlıkla doğrulayabilirsiniz. - Her istekte, isteğe özgü bir `X-Correlation-Id` başlığı bulunur. Destek ekibine yazarken bu değeri paylaşmanız, isteğin kayıtlarda bulunmasını sağlar. - Adresin 4 saniye içinde yanıt vermesi gerekir. Herhangi bir `2xx` yanıt, mesajın teslim alındığı anlamına gelir; yanıt gövdesi dikkate alınmaz. - Zaman aşımı, `2xx` dışındaki bir yanıt ya da bağlantı hatası durumunda mesaj **yeniden gönderilmez**. Bu mesajlara `GET /inbox` ile ulaşılabilir. - Zamanlar saat dilimi bilgisi olmadan, Türkiye saatiyle (UTC+3) `yyyy-MM-dd HH:mm:ss` biçimindedir. Gönderilen gövde (`application/json`, zorunlu) - `messageId` (string, zorunlu): Gelen mesajın kimliği. - `messageDateTime` (string, zorunlu): Mesajın alındığı zaman, `yyyy-MM-dd HH:mm:ss` biçiminde, Türkiye saatiyle. - `sourceNumber` (string, zorunlu): Mesajı gönderen numaranın son 10 hanesi (90 öneki olmadan). - `content` (string, zorunlu): Mesaj metni. - `subscriberNumber` (string, zorunlu): Mesajın geldiği, hesaba ait numara. Örnek gövde: ```json { "messageId": "4815162342", "messageDateTime": "2026-10-27 14:06:12", "sourceNumber": "5xxxxxxxxx", "content": "Merhaba", "subscriberNumber": "850xxxxxxx" } ``` Beklenen yanıtlar: - 200: Mesaj teslim alındı. Herhangi bir `2xx` yanıt aynı anlama gelir.