Webhooks

Overview

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 Webhooks

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.

Reply Notification Webhook

Event Trigger

A new reply SMS is received by WinSMS

Prerequisites

A working Webhook configured and enabled in the WinSMS Client Zone

Request

HTTP/S GET to the Webhook URL configured in the WinSMS Client Zone

Parameters

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 original OUTGOING message with which the reply is associated
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

Example

https://www.yourserver.com/your-web-hook?type=deliver&date=20190128-125744&from=27825550101&text=Send%20one%20from%20Diagon%20Alley&sentmessageid=377&userid=637464

Notes

  • 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”.

Response

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.

Delivery Report Webhook

Event Trigger

WinSMS receives a new delivery/failure report for an SMS

Prerequisites

A working Webhook configured and enabled in the WinSMS Client Zone

Request

HTTP/S GET to the Webhook URL configured in the WinSMS Client Zone

Parameters

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 637464 The unique WinSMS message id originally assigned to the sent message

Example

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”.

Response

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.

State and Status codes

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

Incoming Short/Long Code Webhook

Only available to users with a WinSMS Short/Long Code

Event Trigger

A new incoming SMS is received by a WinSMS Short or Long Code

Prerequisites

A working Short/Long Code Webhook configured and enabled in the WinSMS Client Zone

Request

HTTP/S GET to the Webhook URL configured in the WinSMS Client Zone

Parameters

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

Example

https://www.yourserver.com/your-web-hook?date=20190128-125744&from=27825550101&to=49272&text=Count%20me%20in&userid=637464

Notes

  • To apply for a Short Code or a Long Code number please contact us here and we will send you the necessary application forms.

Response

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.