Webhook: Send and Receive SMS via
Server Application (Simple API)

An SMS Webhook allows your end-user (customers or employees) to send an SMS to retrieve information from your own server. For example, if your end-user sends their zip code via SMS text to the engageSPARK platform, we’ll forward it to your server for processing, and your server’s response (e.g. a weather forecast for that zip code) will be sent back to the end-user.

A webhook is a very simple API for processing SMS on your own server, but without having to write software code to integrate to an API with our system. You simply give us the URL of your application running on your server, and we’ll send the incoming SMS to that URL. The response from your server is then sent back to the end user.

 

Here’s how the webhook works

Let’s say that you want to manage data on your own server (which you are constantly updating or the database is large), but want to receive and send SMS – and not do complex API integration.

On the web platform, choose the engagement type SMS and select Webhook. You may click the Add a Question option where you can type a message or question to send to your contacts to prompt them to send in keywords or a code (this is optional). Below, you will see a required field to enter the URL of your system: it’s titled Webhook: Use Database on Your Server.

When we receive an SMS, we forward it to your server at the URL you specify.  Your server will respond with something (e.g. a location, a weather forecast, and other info) and our system will automatically SMS that response to the person that sent in the code or keyword.

Sample uses

  • People SMS Text the name of their city to get the weather forecast or a crop price
  • Your staff SMS Text in a keyword to query your database server and easily get information
  • Health care workers SMS Text the ID of a patient to lookup patient info from your server
  • Your customer SMS Texts in their order ID to get back status info
  • Customers send in their product serial number to register or lookup warranty information
  • People SMS Text the name of their city or zip code to retrieve the list of your office locations

The data that we will forward to your server when we receive an SMS are:

  1. The content of the SMS
  2. The phone number that the SMS was sent FROM
  3. The phone number that the SMS was sent TO

An example webhook:

Let’s say the URL you enter is “https://www.example.com/application?keyword=”. An SMS comes into our system that says “hello world”, is from the phone number “12345”, and is sent to “67890” (the phone number you’ve linked to your webhook engagement). Our system will then request this URL (via a GET submission):

https://www.example.com/application?keyword=hello%20world&from=12345&to=67890

The response we receive from your server is what we will SMS back to “12345”, i.e., the contact who texted in “hello world”.

NOTE: The query string at the end of your URL must end with a field, such as “message=”  (feel free to use whatever field name you want).

Response structure

  • The response must be plain text, utf-8 encoded.
  • The content type does not matter; the system will take the raw text.
  • The response must have a 200 status code.

Making the webhook more secure on your end

We recommend taking at least one of these following steps to reduce the chances of anyone else accessing your server:

  1. Use SSL encryption to secure the data between our server and your server: use https and not http for your server URL
  2. Add a token as a field value pair in the query string in the URL, for example: https://www.example.com/application?token=token-value&message=
  3. Obfuscate the URL by adding a long, random hash, for example: https://www.example.com/qw8sfcwomc72osbc/application/smsprocessor?token=token-value&message=
    You also can switch the port to a random, uncommonly used port.
  4. Password protect your server; when entering the URL into the webhook engagement, add the username and password to the URL, for example: https://username:password@www.example.com/application?message=

 

Related Articles

Subscription API – Documentation »
Zapier Integration »
Voice Results Webhook »

Have questions or need a little extra help? Get in touch via live chat or drop us a message here: