A Webhook is an HTTP callback that allows a web application to post a message to a URL when certain events take place. Often called “Reverse APIs,” Webhooks can be used to receive data in real time, pass it on to another application, or process the data faster than traditional APIs.
For the user, Webhooks are a way to receive valuable information when it happens, rather than continually polling for that data and receiving nothing valuable most of the time
WinSMS uses Webhooks to let your application know when events happen, such as receiving an SMS message or a delivery status update. When the event occurs, WinSMS makes an HTTP GET request to the URL you configured for the Webhook in the WinSMS Client Zone.
This advanced option allows developers to further integrate incoming SMS replies and delivery/failure reports into existing systems. Eg. The systems that initially sent the outgoing message.
To handle a webhook you only need to build a small web application (written in asp.NET, perl, PHP, Node.js etc.) that can accept the HTTP requests. If you already have a web application set up, handling a webhook is usually as easy as adding a new URL to your application.
With this web application in place, you can have reply notifications and delivery reports sent from WinSMS, interact with your internal systems, and dynamically create appropriate system responses. Eg Send a response to an incoming message, or retry or blacklist a failed delivery.
Developers can configure and test their Webhooks using the tools provided in the My Profile -> Developers panel of the WinSMS Client Zone.
A new reply SMS is received by WinSMS
A working Webhook configured and enabled in the WinSMS Client Zone
HTTP/S GET to the Webhook URL configured in the WinSMS Client Zone
| Name | Example | Description |
|---|---|---|
| type | deliver | This will always be deliver for Reply Notifications |
| date | 20190128-125744 | Message time stamp, formatted YYYYMMDD-HHMMSS. (GMT+2) |
| from | 27825550101 | Telephone number from which the message was sent |
| text | Send one from Diagon Alley | The message text |
| sentmessageid | 377 | The unique WinSMS message id assigned to the most recent OUTGOING message sent to the from number |
| sentmessagetext | Where can I get a dragon | The message text of the most recent OUTGOING message sent to the from number |
| userid | 637464 | The unique WinSMS account number (User Id) of the account that sent the original OUTGOING message. This is handy if you use the same Webhook URL for multiple WinSMS Accounts or Sub Accounts |
| to | 27990003005 | Unused parameter |
| sign | be4a9aa0152a80976903d32064f3daca | For Internal Use |
https://www.yourserver.com/your-web-hook?type=deliver&date=20190128-125744&from=27825550101&text=Send%20one%20from%20Diagon%20Alley&sentmessageid=377&sentmessagetext=Where%20can%20I%20get%20a%20dragon&userid=637464
- Reply Notification Webhooks and Delivery Report Webhooks can be enabled separately in the WinSMS Client Zone Developers Panel, though BOTH callbacks will be delivered to the same URL.
The two Webhook callbacks can be differentiated by the type parameter in the GET request to the URL. Delivery Reports will be represented by a type parameter of “report” and Reply Notifications will be represented by a type parameter of “deliver”.
The Webhook should respond with an HTTP Status Code 200, to indicate that it acknowledges receipt of the notification.
Failure to do so will result in WinSMS attempting the Webhook callback a subsequent 3 times, at intervals of 60 seconds.
WinSMS receives a new delivery/failure report for an SMS
A working Webhook configured and enabled in the WinSMS Client Zone
HTTP/S GET to the Webhook URL configured in the WinSMS Client Zone
| Name | Example | Description |
|---|---|---|
| type | report | This will always be report for Delivery Reports |
| date | 20190128-125744 | The date the message was originally sent, formatted YYYYMMDD-HHMMSS. (GMT+2) |
| sdate | 20190128-125801 | The Status Date of the message – the date it was delivered or failed, formatted YYYYMMDD-HHMMSS. (GMT+2) |
| from | 27825550101 | The telephone number to which the message was sent |
| state | DELIVERED | The final state of the message – DELIVERED, UNDELIV etc. – Refer to the table below for possible values |
| status | 0 | Integer code representing the current state of the message. Refer to the table below for possible values |
| sentmessageid | 6374648 | The unique WinSMS message id originally assigned to the sent message |
| userid | 37835 | The unique WinSMS account number (User Id) of the account that owns the Short/Long Code. This is handy if you use the same Webhook URL for multiple WinSMS Accounts or Sub Accounts |
| text | - | Unused parameter |
| sign | be4a9aa0152a80976903d32064f3daca | For Internal Use |
https://www.yourserver.com/your-web-hook?type=report&date=20190128-125744&sdate=20190128-125801&from=27825550101&state=DELIVERED&status=0&sentmessageid=637464
- Reply Notification Webhooks and Delivery Report Webhooks can be enabled separately in the WinSMS Client Zone Developers Panel, though BOTH callbacks will be delivered to the same URL.
The two Webhook callbacks can be differentiated by the type parameter in the GET request to the URL. Delivery Reports will be represented by a type parameter of “report” and Reply Notifications will be represented by a type parameter of “deliver”.
The Webhook should respond with an HTTP Status Code 200, to indicate that it acknowledges receipt of the notification.
Failure to do so will result in WinSMS attempting the Webhook callback a subsequent 3 times.
| status | state | Description |
|---|---|---|
| 0 | DELIVERED | |
| 101 | EXPIRED | Undelivered: expired in transit |
| 102 | DELETED | Undelivered: message cancelled before being delivered |
| 103 | UNDELIV | Undelivered: message could not be delivered |
| 107 | REJECTD | Undelivered: message was rejected |
Only available to users with a WinSMS Short/Long Code
A new incoming SMS is received by a WinSMS Short or Long Code
A working Short/Long Code Webhook configured and enabled in the WinSMS Client Zone
HTTP/S GET to the Webhook URL configured in the WinSMS Client Zone
| Name | Example | Description |
|---|---|---|
| date | 20190128-125744 | Message time stamp, formatted YYYYMMDD-HHMMSS. (GMT+2) |
| from | 27825550101 | Telephone number from which the message was sent |
| to | 49272 | Short/Long Code to which the message was sent |
| text | Count me in | The message text sent to the Short/Long Code |
| userid | 637464 | The unique WinSMS account number (User Id) of the account that owns the Short/Long Code. This is handy if you use the same Webhook URL for multiple WinSMS Accounts or Sub Accounts |
| type | - | Unused parameter |
| sign | be4a9aa0152a80976903d32064f3daca | For Internal Use |
https://www.yourserver.com/your-web-hook?date=20190128-125744&from=27825550101&to=49272&text=Count%20me%20in&userid=637464
- To apply for a Short Code or a Long Code number please contact us here and we will send you the necessary application forms.
The Webhook should respond with an HTTP Status Code 200, to indicate that it acknowledges receipt of the notification.
Failure to do so will result in WinSMS attempting the Webhook callback a subsequent 3 times.