The author voluntarily contributed this tutorial as a part of Pepipost Write to Contribute program.

Introduction

Heard about Webhooks a lot but have no idea what they are? Thinking on how to setup a webhook but don't know how to? In this article, we will talk everything about webhooks, right from what are webhooks to discord webhooks and how to set them up!

Let's start with the tutorial.

What are Webhooks?

Webhook is very simple and understanding the webhook’s working mechanism is much simpler too. Ideally, it sends a notification (data) on a particular URL mostly via POST method request on every activity/action of the user. Technically, you need to share a publicly accessible URL with the provider and whenever an action or activity is performed by the user, data will be posted on the client-side application server on which your webhook URL is configured to consume that data.

Types of Webhooks | Github, Stripe, Plex, Slack Webhooks

Webhook has many different names such as “Reverse API”, “web callback” or “HTTP push API”.

Many applications allow you to set up webhooks for tracking your realtime activities. Here are a sample list of products who over webhooks integration:

1) Github (extensively used among developers, notifies for every activity/action on your repository).

2) Slack (Slack webhook notifies you on a particular channel on a particular activity - any integration related to development or third party)

3) Facebook (Receive real-time notifications of changes to your Facebook Page)

4) Pepipost (notifies you on every activity on email)*

How to Set up a webhook?

1) Make sure your port 80 and 443 (default it changes as per your configuration) are open for your webhook provider ie. it should be publicly accessible.

Check using telnet:

telnet webhook.mydomain.com 80{443 or any other port}

If the URL is open it will give below results:

   Connected to webhook.mydomain.com.
   Escape character is '^]'.
   ^]
   telnet> quit
   Connection closed.

2) Prepare a URL that you need to share with your webhook provider.
ie. deploying a piece of code (webhook receiving module) for consuming data which will be posted by the provider.

Writing Webhooks in PHP

If PHP is installed on your web server you can simply copy & paste the below code snippet in file getwebhooks.php at your web server location.

Default locations

Apache webserver:

/var/www/html/getwebhooks.php

Nginx webserver:

/usr/share/nginx/html/getwebhooks.php

If you have the custom path:

/{path to web server}/getwebhooks.php

getwebhooks.php

<?php
$webhook_data = file_get_contents('php://input');
file_put_contents('/tmp/consumewebhook.log', $webhook_data)
?>

Writing Webhooks in Python

Similarly, for python install/update web, six packages using below command:

sudo pip install web.py==0.40

{whichever is latest}

sudo pip install six --upgrade

Copy-paste the below code snippet in file getwebhooks.py

import web
urls = ('/.*', 'getwebhooks')
app = web.application(urls, globals())
class getwebhooks:
    def POST(self):
        data = web.data()
        print
        print 'DATA RECEIVED:'
        print data
        print
        return 'OK'

if __name__ == '__main__':
    app.run()

Run using:

python getwebhooks.py 6565

(if Port not specified default it will take 8080)

Test by hitting below command from the terminal.

curl -v --request POST --url http://mydomain.webhooks.example:6565/webhook --header 'Content-Type: application/json' --data '[{“hello”:”world”}]’

What kind of data will be received in a webhook POST request (consuming webhooks)?

Data posted on your webhook URL will be mostly JSON.

Most of the webhooks, POST data to you in JSON format besides JSON there will be 2 more ways XML or form-data (application/x-www-form-urlencoded or multipart/form-data). No matter what content-type is posted to you, almost all web library will support or help you in interpreting.

If in case, it doesn’t have, you will be able to write one or two functions of your own.

How to test webhook URL (Sending a POST request with data)?

You can send data using an API / REST Development tools but posting data can be tedious at times. Since the webhook calls are asynchronous you need to wait for the response after triggering an event.

But there are already available tools and with the help of those, you can always check the response without any setup.

2 popular HTTP events logging sites are:

1. Webhook Site
   undefined
   
2. Request bin
   
   
   All you need is the URL they provide and hit any curl request to particular URL they will help you render the posted data on their UI.

Some of the famous REST development tools can be used to post or receive data:

• Postman (popular)
• Advanced REST Client(ARC)
• Paw
• HttpRequester
• Curl through terminal

You can always try with your existing web-server on localhost or create one with ngrok.

Simply hit the below command on your terminal:

curl -v --request POST --url http://yourwebhook.domain.com/getwebhooks --header 'Content-Type: application/json' --data '[{"SIZE":null,"SUBJECT":"Thank you for your interest in account","TRANSID":"15086970014684020","RESPONSE":"74.xxx.xx.27 - smtp;250 2.0.0 OK 1508714170 x69si1901723otb.460 -gsmtp","RCPTID":"0","EMAIL":"[email protected]","TAGS":"Content","TIMESTAMP":"1508714170","CLIENTID":"xxxx","FROMADDRESS":"[email protected]","MSIZE":"9697","X-APIHEADER":"Content","EVENT":"sent"}]'

Note: Above is a Pepipost sample webhook data whose content-type is application/JSON it may vary with respect to your webhook provider.

How to secure your webhook URL (security)?

Since webhook URLs are mostly publicly open, there will be always a security concern of someone accessing URL and posting improper data. There are many ways to implement security on the URL but few most important are as follows :

• Allow only TLS connections (HTTPS): TLS ensures that data is encrypted over the internet with the help of some secure algorithm and it should be not viewable by any third party while transmission. By default every web servers support TLS.
• Basic security among all is to keep an Auth token: eg. ?mysecure=PEPIA token is meant to validate whether the source is authentic or not. These tokens are used to check whether the source has access for reading/modifying application. Restricting unknown source will help to prevent useless data which automatically increase the availability of your URL.
• Implement all the basic access authentication which is required by any HTTP user-agent: This is the simplest technique of enforcing access controls to your web resources because it does not require any cookies, sessions or login pages rather it uses simple HTTP-header authentication method. Basic authentication usually takes action with HTTPS to provide confidentiality.

Conclusion

Webhooks play a vital role in this modern world where bots revert on responses. It not only keeps us updated on a real-time basis but helps to fix, solve, take a specific action on the data posted on the URL.