Stop Polling. Get Notified When SMS Statuses Change.
Instead of repeatedly checking message statuses through the API, receive webhook notifications for supported events.
Reduce Unnecessary API Calls
Receive SMS status updates through webhooks instead of repeatedly requesting delivery information.
Automate Your Workflows
Use webhook events to update records, generate reports, or trigger actions within your application.
Track Delivery Outcomes
Monitor message delivery results and inbound SMS through event notifications sent to your system.
One Event, Four Steps
Send or Receive an SMS
Send messages through the TurkeySMS dashboard or API, or receive an SMS on your 0850 number.
An Event Occurs
When a supported event occurs, such as a message status update, TurkeySMS prepares an event notification and signs it if a signing secret is set.
Webhook Delivery
TurkeySMS sends the notification with a POST request to your configured HTTPS endpoint.
Process the Event
Your application verifies the notification, returns a 2xx response and processes the event data.
The diagram is for illustration only and is not a timing commitment. How the event is processed in your system depends on your own integration.
Which Events Can You Receive?
You choose the events you want to receive in your webhook settings.
sms.sent
Available NowWhen your message is handed over to the operator.
sms.delivered
Available NowWhen a successful delivery report arrives from the operator.
sms.received
Available NowWhen an SMS arrives on your 0850 number. Because it contains the message text, it is only sent if you explicitly select it in the settings.
inbound.matched
Available NowWhen the "Fire Webhook" action runs in one of your inbound SMS automation rules. It is sent to the first active webhook in your account. Inbound SMS
key.test
Available NowWhen you press the Test button in the dashboard; it is for testing your connection.
Outgoing message events do not include the message text; inbound SMS events include the message text and the sender's number.
Explore a Webhook Payload
See an example of the event data your application receives and how webhook signatures can be verified.
Example payload with sample values. Refer to the API documentation for the current schema. This demo runs in your browser; no request is sent.
{
"id": "27f38025030d060f3e3b760b318b406e",
"event": "sms.delivered",
"created_at": "2026-10-01T15:30:03+03:00",
"timestamp": 1790857803,
"data": {
"message_id": 518431556,
"bulk_id": "1259383818",
"to": "905xxxxxxxxx",
"sender_id": "BASLIGIM",
"parts": 1,
"source": "api",
"key_id": 1001,
"sent_at": "2026-10-01T15:28:31+03:00",
"done_at": "2026-10-01T15:28:33+03:00",
"operator_status": "Message delivered to handset",
"status": "delivered"
}
}Signing secret in your account (signs the notification): demo-secret
Computing…
This demo does not check the time window (300 s); your real receiver must also check the t= value in the signature.
- Read the request body exactly as received (raw).
- Split the X-TurkeySMS-Signature-V2 value into t (timestamp) and v1 (signature).
- Compute HMAC(t + "." + body) with your signing secret.
- Compare the result with the signature in constant time and check that t is recent (300 s); if they do not match, return 401.
Note: An HTTP 2xx response means the event was received, not that your business process completed successfully. Process each event once, using its delivery ID.
Signed, Verifiable Notifications
HMAC Signatures
Verify webhook signatures to check the authenticity and integrity of incoming notifications. When you set a signing secret, notifications are signed with SHA-256 or SHA-512 HMAC; without a secret, no signature headers are sent.
Timestamped Signature (V2)
The V2 signature also covers the timestamp. By checking the time in the signature, your receiver can block old requests from being reused.
Delivery ID
Each event keeps the same ID across retries, so you can filter out duplicates.
No Delivery to Local Addresses
localhost and private network addresses are not accepted as webhook addresses.
What Happens if Your Server Does Not Respond?
If your endpoint cannot accept a notification, TurkeySMS handles the unsuccessful delivery attempt according to the retry policy below.
Retry on error responses
Stops on a 400 response
Pausing
The same event may be delivered more than once. Use a stable event identifier to handle duplicate notifications safely. Respond first, then process: store the event and return 2xx immediately; your server needs to respond within about 10 seconds.
Track Webhook Deliveries in Your Dashboard
Review webhook delivery statuses, response results, and available retry records from your dashboard.
What Can You Do with Webhooks?
CRM Integration
Associate SMS delivery updates with customer records in your CRM.
sms.deliveredOrder Communications
Track SMS delivery outcomes alongside your order and customer notification workflows.
sms.sentsms.deliveredReporting & Analytics
Send supported SMS status events to your reporting systems for analysis and monitoring.
sms.sentsms.deliveredInbound SMS Tracking
Pass customer replies to your support or ticketing system as records. Inbound SMS
sms.receivedSet Up Your Webhook in Three Steps
Prepare Your Endpoint
Create an HTTPS endpoint in your application to receive webhook notifications, and have an API key in your account for the webhook.
Configure Your Webhook
In My Account → API Center → Security & IP → Webhook, choose the API key, add your endpoint URL and signing secret, and select the supported events you want to receive.
Verify and Test
Use the Test button or the Webhook Simulator, validate incoming signatures and confirm that your application processes events correctly; follow deliveries in the Webhook Center.
What Do You Need to Get Started?
TurkeySMS Account
API Key and Signing Secret
HTTPS Endpoint
Webhooks
Event Source
Need help with the setup? We Call You
Frequently Asked Questions
What is an SMS webhook, and how is it different from the SMS API?
With the SMS API, you send requests to TurkeySMS (for example, to send a message or check its status). A webhook works the other way round: when an event occurs, TurkeySMS sends a notification to the address you set. So you no longer need to keep polling the API to learn the status.
Which SMS events are supported?
sms.sent (when the message is handed over to the operator), sms.delivered (when the delivery report arrives), sms.received (when an SMS arrives on your 0850 number; only if explicitly selected), inbound.matched (when "Fire Webhook" runs in your inbound SMS automation) and key.test (the Test button).
When are webhook notifications sent?
After an event occurs, it is queued and sent to your address. We do not commit to a delivery time for notifications; the operator report, retries and your server's response all affect timing. You can always see a message's final status in your SMS reports.
What happens if my endpoint is unavailable?
If your server returns a 5xx response or times out, the event is resent at increasing intervals. A 400 response is treated as a permanent error and the event is not resent. Your server needs to respond within about 10 seconds.
Can the same event be delivered more than once?
Yes, for example on a retry after a timeout. Each event's ID (X-TurkeySMS-Delivery) stays the same across retries; if you receive an ID you have already processed, return 2xx without processing it again.
How do I verify webhook signatures?
When you set a signing secret, every request includes the X-TurkeySMS-Signature-V2 header; without a secret, no signature headers are sent. Compute the HMAC from the raw body and the timestamp in the signature, then compare; details and code samples are in the API documentation.
How can I test my webhook integration?
Use the Test button in My Account → API Center → Security & IP → Webhook: it sends a key.test event and shows the HTTP code and duration. The Webhook Simulator sends the event you choose with a real signature and the flag "simulated": true. Then check the delivery records in the Webhook Center.
Is there an additional charge for webhooks?
No, there is no extra fee for using webhooks. Sending events require SMS sending (an SMS package), and inbound SMS events require an 0850 number allocated to your account.
If I pause a webhook, are events lost?
No events are sent to a paused webhook. When you re-enable it, events from the paused period are not sent; you can see the statuses for that period in your SMS reports.
Where does the "Fire Webhook" action send to?
The "Fire Webhook" action in inbound SMS automation sends the "inbound.matched" event to the first active webhook in your account.
Does the message text come with the webhook?
Outgoing message events (sms.sent, sms.delivered) do not include the message text. Inbound SMS events (sms.received, inbound.matched) include the message text and the sender's number; store this data in line with KVKK (Turkish data protection law).
Connect SMS Delivery Updates to Your Application
Explore TurkeySMS webhook integration, configure your endpoint, and start processing supported SMS status notifications in your own system. Creating an account is free.