Webhook Notifications Quick Start
Welcome to the RingCentral Platform. RingCentral is the leading unified communications platform. From one system developers can integrate with, or build products around all the ways people communicate today: SMS, voice, fax, chat and meetings.
In this Quick Start, we are going to help you create a Webhook push notifications app using our Push Notifications API, which allows your application receiving notifications on instant SMS message events. Let's get started.
Create an App
The first thing we need to do is create an app in the RingCentral Developer Portal. This can be done quickly by clicking the "Create Notifications App" button below. Just click the button, enter a name and description if you choose, and click the "Create" button. If you do not yet have a RingCentral account, you will be prompted to create one.
Create Webhook App Show detailed instructions
- Login or create an account if you have not done so already.
- Go to Console/Apps and click 'Create App' button.
- Select "REST API App" under "What type of app are you creating?" Click "Next."
- Under "Authentication" select "Password-based auth flow."
- Under "Security" add the following permissions:
- WebhookSubscriptions
- SMS
When you are done, you will be taken to the app's dashboard. Make note of the Client ID and Client Secret. We will be using those momentarily.
Download and edit a .env
file
Follow the instructions found in our guide to running Developer Guide code samples. Or:
- Download our env-template and save it as a file named
.env
. - Edit your newly downloaded
.env
file, setting its variables with the proper values for the app you created above.
Subscribe for push notification
Select your preferred language below.
Install RingCentral JavaScript SDK
$ npm install ringcentral --save
$ npm install dotenv --save
Run ngrok to create a localhost tunnel
$ ngrok http 5000
Copy the forwarding address, e.g. https://54a0541a.ngrok.io, and append the path "/webhook" to the address then paste it into the DELIVERY_ADDRESS variable in the code below.
Create and edit webhook-notification.js
Create a file called webhook-notification.js using the contents below.
const RC = require('@ringcentral/sdk').SDK
var http = require('http');
require('dotenv').config();
PORT = 5000
DELIVERY_ADDRESS = '<https://xxxxxxxx.ngrok.io/webhook>'
var server = http.createServer(function(req, res) {
if (req.method == 'POST') {
if (req.url == "/webhook") {
if (req.headers.hasOwnProperty("validation-token")) {
res.setHeader('Content-type', 'application/json');
res.setHeader('Validation-Token', req.headers['validation-token']);
res.statusCode = 200;
res.end();
} else {
var body = []
req.on('data', function(chunk) {
body.push(chunk);
}).on('end', function() {
body = Buffer.concat(body).toString();
var jsonObj = JSON.parse(body)
console.log(jsonObj.body);
});
}
}
} else {
console.log("IGNORE OTHER METHODS")
}
});
server.listen(PORT);
var rcsdk = new RC({
'server': process.env.RC_SERVER_URL,
'clientId': process.env.RC_CLIENT_ID,
'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({
'username': process.env.RC_USERNAME,
'password': process.env.RC_PASSWORD,
'extension': process.env.RC_EXTENSION
})
platform.on(platform.events.loginSuccess, function(e) {
console.log("Login success")
subscribe_for_notification()
});
async function subscribe_for_notification() {
var params = {
eventFilters: ['/restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS'],
deliveryMode: {
transportType: "WebHook",
address: DELIVERY_ADDRESS
}
}
try {
var resp = await platform.post('/restapi/v1.0/subscription', params)
var jsonObj = await resp.json()
console.log(jsonObj.id)
console.log("Ready to receive incoming SMS via WebHook.")
} catch (e) {
console.error(e.message);
throw e;
}
}
Run your code
You are almost done. Now run your script.
$ node webhook-notification.js
Install RingCentral Python SDK
$ pip install ringcentral python-dotenv
Run ngrok to create a localhost tunnel
$ ngrok http 5000
Copy the forwarding address e.g. https://54a0541a.ngrok.io and append the path "/webhookcallback" to the address then paste it into the DELIVERY_ADDRESS variable in the code below.
Note: Running the demo code requires Python 3.x
Create and edit webhook-notification.py
Create a file called webhook-notification.py using the contents below.
from ringcentral import SDK
DELIVERY_ADDRESS= '<https://XXXXXXXX.ngrok.io/webhookcallback>'
rcsdk = SDK( os.environ.get('RC_CLIENT_ID'),
os.environ.get('RC_CLIENT_SECRET'),
os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
platform.login(os.environ.get('RC_USERNAME'),
os.environ.get('RC_EXTENSION'),
os.environ.get('RC_PASSWORD') )
except:
sys.exit("Unable to authenticate to platform. Check credentials.")
try:
eventFilters = ['/restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS']
params = {
"eventFilters" : eventFilters,
"deliveryMode": {
"transportType": 'WebHook',
"address": DELIVERY_ADDRESS
}
}
res = platform.post("/subscription", params)
except Exception as e:
print(f"An exception was thrown: {e}")
else:
print(f'{res}')
Create and Edit webhook-server.py
Create a file called webhook-server.py.
from http.server import BaseHTTPRequestHandler, HTTPServer
class S(BaseHTTPRequestHandler):
def do_POST(self):
path = self.path
if path == "/webhookcallback":
validationToken = self.headers['Validation-Token']
if validationToken is not None:
self.send_response(200)
self.send_header('Content-type', 'application/json')
self.send_header('Validation-Token', validationToken)
return self.end_headers()
else:
content_len = int(self.headers.get('Content-Length'))
payload = self.rfile.read(content_len)
print (payload)
return
else:
print ("Ignore this")
def run(server_class = HTTPServer, handler_class = S, port=5000):
server_address = ('', port)
httpd = server_class(server_address, handler_class)
print ('Starting httpd...')
httpd.serve_forever()
if __name__ == "__main__":
from sys import argv
if len(argv) == 2:
run(port=int(argv[1]))
else:
run()
Run your code
You are almost done. Now run your script.
Open a terminal window and run the server code.
$ python3 webhook-server.py
Open another terminal window and run the app
$ python3 webhook-notification.py
Install RingCentral PHP SDK
$ curl -sS https://getcomposer.org/installer | php
$ php composer.phar require ringcentral/ringcentral-php vlucas/phpdotenv
Run ngrok to create a localhost tunnel
$ ngrok http 5000
Copy the forwarding address e.g. https://54a0541a.ngrok.io and append the path "/webhook-notification.php?webhookcallback" to the address then paste it into the $DELIVERY_ADDRESS variable in the code below.
Create and Edit webhook-notification.php
Create a file called webhook-notification.php using the contents below.
<?php
require('vendor/autoload.php');
$DELIVERY_ADDRESS='<https://xxxxxxxx.ngrok.io/webhook-notification.php?webhookcallback>';
$rcsdk = new RingCentral\SDK\SDK( $_ENV['RC_CLIENT_ID'],
$_ENV['RC_CLIENT_SECRET'],
$_ENV['RC_SERVER_URL'] );
$platform = $rcsdk->platform();
if (isset($_REQUEST['webhookcallback'])){
if (array_key_exists('HTTP_VALIDATION_TOKEN', $_SERVER)) {
header("Content-type: application/json");
return header("Validation-Token: {$_SERVER['HTTP_VALIDATION_TOKEN']}");
}else{
$jsonStr = file_get_contents('php://input');
$jsonObj = json_decode($jsonStr, TRUE);
print_r($jsonObj['body']['subject']);
}
}else{
$platform->login( $_ENV['RC_USERNAME'],
$_ENV['RC_EXTENSION'],
$_ENV['RC_PASSWORD'] );
$params = array(
'eventFilters' => array(
'/restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS'
),
'deliveryMode' => array(
'transportType' => "WebHook",
'address' => $DELIVERY_ADDRESS
));
try {
$apiResponse = $platform->post('/subscription', $params);
print_r ("Response: " . $apiResponse->text());
}catch (Exception $e){
print_r ("Exception: " . $e->getMessage());
}
}
Run your code
You are almost done. Now run your script.
Open a terminal window and start PHP server.
$ php -S localhost:5000
$ php webhook-notification.php
Now you can send an SMS message to the extension's phone number to see how you'll receive the notification.
Create a Java project (using Eclipse IDE)
- Create a new Java project
- Select the Gradle Project wizard
- Enter project name "WebHook"
- Open the build.gradle file and add the RingCentral Java SDK to the project as shown below:
dependencies {
// ...
compile 'com.ringcentral:ringcentral:1.0.0-beta10'
}
Create a new Java Class
Select "File -> New -> Class" to create a new Java class named "SubscribeForWebHookNotification"
package SubscribeForWebHookNotification;
public class SubscribeForWebHookNotification {
public static void main(String[] args) {
// TODO Auto-generated method stub
}
}
Edit the file "SubscribeForWebHookNotification.java".
Be sure to edit the variables in ALL CAPS with your app and user credentials. Be sure to also set the recipient's phone number.
Run ngrok to create a localhost tunnel
$ ngrok http 5000
Copy the forwarding address e.g. https://54a0541a.ngrok.io and paste it into the DELIVERY_ADDRESS variable in the code below.
package com.ringcentral;
import java.io.IOException;
import com.ringcentral.RestException;
import com.ringcentral.definitions.CreateSubscriptionRequest;
import com.ringcentral.definitions.NotificationDeliveryModeRequest;
public class SubscribeForWebHookNotification
{
static RestClient rc;
public static void main(String[] args) throws IOException, RestException
{
String DELIVERY_ADDRESS = "<https://xxxxxxxxx.ngrok.io>";
rc = new RestClient( System.getenv("RC_CLIENT_ID"),
System.getenv("RC_CLIENT_SECRET"),
System.getenv("RC_SERVER_URL") );
try {
rc.authorize( System.getenv("RC_USERNAME"),
System.getenv("RC_EXTENSION"),
System.getenv("RC_PASSWORD") );
} catch (RestException | IOException e) {
e.printStackTrace();
}
var eventFilters = new String[] {
"/restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS"
};
CreateSubscriptionRequest createSubscriptionRequest
= new CreateSubscriptionRequest()
.eventFilters(eventFilters)
.deliveryMode( new NotificationDeliveryModeRequest()
.transportType("WebHook")
.address(DELIVERY_ADDRESS)
);
var result = rc.restapi().subscription().post(createSubscriptionRequest);
System.out.println(result.id);
System.out.println("WebHook Ready");
rc.revoke();
}
}
Create a WebHookServer
We use Jetty embedded for our server. You can get it here.
Browse to the WebHook
project folder and create a WebHookServer project
$ cd WebHook
$ curl -o jetty-all-uber.jar https://repo1.maven.org/maven2/org/eclipse/jetty/aggregate/jetty-all/9.4.19.v20190610/jetty-all-9.4.19.v20190610-uber.jar
$ touch WebhookServer.java
$ open WebhookServer.java
Edit the WebhookServer.java
with code below:
package com.ringcentral;
import java.io.IOException;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.eclipse.jetty.server.Request;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.server.handler.AbstractHandler;
public class WebhookServer extends AbstractHandler
{
@Override
public void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response)
throws IOException, ServletException
{
response.setStatus(HttpServletResponse.SC_OK);
response.setHeader("Validation-Token", request.getHeader("Validation-Token"));
if (request.getMethod() == "POST")
{
String body = request.getReader().lines().collect(java.util.stream.Collectors.joining(System.lineSeparator()));
System.out.println(body);
}
response.getWriter().println("OK");
baseRequest.setHandled(true);
}
public static void main( String[] args ) throws Exception
{
Server server = new Server(5000);
server.setHandler(new WebhookServer());
server.start();
server.join();
}
}
Build and run the WebHook Server
$ mkdir classes
$ javac -d classes -cp jetty-all-uber.jar WebHookServer.java
$ java -cp classes:jetty-all-uber.jar com.ringcentral.WebHookServer
Now run the SubscribeForWebHookNotification app from Eclipse.
Send an sms to RINGCENTRAL_USERNAME
phone number, and watch the output on the WebHookServer terminal window.
We use .NET core which is cross-platform. You can get it here.
Create a solution
mkdir webhook-demo
cd my-solution
dotnet new sln
Create WebHook Server project
cd webhook-demo
mkdir webhook-server
cd webhook-server
dotnet new web
cd ..
dotnet sln add ./webhook-server/webhook-server.csproj
cd webhook-server
Edit Startup.cs
and override its content with code below:
using System;
using System.IO;
using System.Text;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Primitives;
namespace webhook_server
{
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment()) app.UseDeveloperExceptionPage();
app.Run( async (context) =>
{
context.Request.Headers.TryGetValue("Validation-Token", out StringValues validationToken);
context.Response.Headers.Add("Validation-Token", validationToken);
if (context.Request.Path == "/webhook" && context.Request.Method == "POST")
{
using (StreamReader reader = new StreamReader(context.Request.Body, Encoding.UTF8))
{
var str = reader.ReadToEnd();
Console.WriteLine(str);
}
}
});
}
}
}
Run ngrok to create a localhost tunnel
$ ngrok http 5000
Copy the forwarding address e.g. https://54a0541a.ngrok.io and append the path "/webhook" to the address then paste it into the DELIVERY_ADDRESS
variable in the code below.
Create Setup WebHook project
cd my-solution
mkdir setup-webhook
cd setup-webhook
dotnet new console
cd ..
dotnet sln add ./setup-webhook/setup-webhook.csproj
cd setup-webhook
dotnet add package RingCentral.Net
Edit setup-webhook.csproj
file and add <LangVersion>latest</LangVersion>
to <PropertyGroup>
.
Edit Program.cs
file and override its content with code below. Be sure to edit the variables in
using System;
using System.Threading.Tasks;
using RingCentral;
namespace setup_webhook
{
class Program
{
static RestClient restClient;
const string DELIVERY_ADDRESS = "<https://xxxxxxxx.ngrok.io/webhook>";
static async Task Main(string[] args)
{
restClient = new RestClient(
Environment.GetEnvironmentVariable("RC_CLIENT_ID"),
Environment.GetEnvironmentVariable("RC_CLIENT_SECRET"),
Environment.GetEnvironmentVariable("RC_SERVER_URL"));
restClient.Authorize(
Environment.GetEnvironmentVariable("RC_USERNAME"),
Environment.GetEnvironmentVariable("RC_EXTENSION"),
Environment.GetEnvironmentVariable("RC_PASSWORD")).Wait();
await rc.Restapi().Subscription().Post(new CreateSubscriptionRequest
{
eventFilters = new[] {"/restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS"},
deliveryMode = new NotificationDeliveryModeRequest
{
transportType = "WebHook",
address = DELIVERY_ADDRESS
}
});
Console.WriteLine("WebHook ready!");
}
}
}
Run your code
You are almost done. Now run your script.
cd my-solution
cd webhook-server
dotnet run
Open a new terminal and run:
cd my-solution
cd setup-webhook
dotnet run
Test the app
Send an sms to RINGCENTRAL_USERNAME
phone number, and watch the output of my-solution/webhook-server project.
Install RingCentral Ruby SDK
$ gem install ringcentral-sdk
$ gem install dotenv
$ gem install sinatra
Run ngrok to create a localhost tunnel
$ ngrok http 5000
Copy the forwarding address e.g. https://54a0541a.ngrok.io and paste it into the DELIVERY_ADDRESS variable in the code below.
Create and Edit webhook-notification.rb
Create a file called webhook-notification.py. Be sure to edit the variables in ALL CAPS with your app and user credentials.
require 'ringcentral'
require 'dotenv/load'
DELIVERY_ADDRESS = '<https://xxxxxxxx.ngrok.io>'
$rc = RingCentral.new( ENV['RC_CLIENT_ID'],
ENV['RC_CLIENRT_SECRET'],
ENV['RC_SERVER_URL'] )
$rc.authorize( username: ENV['RC_USERNAME'],
extension: ENV['RC_EXTENSION'],
password: ENV['RC_PASSWORD'] )
r = $rc.post('/restapi/v1.0/subscription', payload: {
eventFilters: ['/restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS'],
deliveryMode: { transportType: 'WebHook', address: DELIVERY_ADDRESS }
})
puts r.body['id']
puts "WebHook Ready"
$rc.revoke()
Create and Edit webhook-server.rb
Create a file called webhook-server.rb.
require 'sinatra'
set :port, 5000
post '/' do
status 200
headers('Content-Type' => 'application/json')
headers('Validation-Token' => request.env['HTTP_VALIDATION_TOKEN']) if request.env['HTTP_VALIDATION_TOKEN']
request.body.rewind
body = request.body.read
puts body
# do whatever with body
body 'OK'
end
Run your code
You are almost done. Now run your script.
Open a terminal window and run the server code.
$ ruby webhook-server.rb
Open another terminal window and run the app
$ ruby webhook-notification.rb
Now you can send an SMS message to the extension's phone number to see how you'll receive the notification.
Graduate Your App
Congratulations on creating your first RingCentral application. The last step is to graduate your application. We recommend going through this process for your first application so you can understand the steps to take in the future, but also to come to appreciate the care taken by RingCentral to ensure that only high-quality apps are allowed into our production environment.