Webhooks Integration Guide
Version 2.0
Confidential Falconide Webhooks Integration Guide Version 1.1
Contents
1. Overview ................................................................................................................................................................................................................................................................ 3
2. How does Data transmission happen? .................................................................................................................................................................................................................. 4
3. How to Configure Webhooks ................................................................................................................................................................................................................................. 5
4. Events Data ............................................................................................................................................................................................................................................................ 7
5. How to collect the event data? .............................................................................................................................................................................................................................. 9
6. Track your Webhooks ............................................................................................................................................................................................................................................ 9
7. Support................................................................................................................................................................................................................................................................... 9
2
Confidential Falconide Webhooks Integration Guide Version 1.1
1. Overview
Webhook is a feature in Falconide that enables real-time data syncing between Falconide and your system. A Webhook is an HTTP callback: an HTTP POST that occurs
when an event like email open or click occurs and sends back information. Instead of having to poll our API constantly to check for updates, Falconide sends the data
to your system at the instant an event occurs.
3
Confidential Falconide Webhooks Integration Guide Version 1.1
2. How does Data transmission happen?
When any of the events out of the ones you have specified occurs, a call back URL sends an HTTP POST request to the URL you have specified and delivers the events
to your end point. If you haven’t specified any URL, or the URL takes too long to respond (more than 60 seconds), the Webhook call is considered failed with no retries
are allowed. Such failed calls are logged in to the database, and you can download the log from the panel. A notification is sent to the email address you specify. Data
is shared over HTTP POST to your preconfigured Webhooks URL.
You may use a HTTP or a HTTPS URL for Webhooks. In most cases HTTP is sufficient, but HTTPS can be useful if your data is sensitive or if you wish to protect against
replay attacks for example.
Falconide Webhooks support the following events:
sent: when the email is delivered to the receiving server.
dropped: when the email address is dropped. Users who have unsubscribed in past or are blacklisted because of hard bounce/Spam complaints are treated
as dropped. Once dropped, no email communication is allowed on these ids.
invalid: when any event is not processed due to invalid or incorrect email ID. All API requests with syntactically incorrect email ids will be treated as Invalid
and no further processing will be done on such ids. You can capture all such invalid events in real time and try correcting them offline.
bounced: when the email bounces, that is, the receiving server could not or does not accept message due to reasons like server not being reachable, or email
id doesn’t exists etc. Hard bounces from an email address lead to its blacklisting in Falconide system.
opened: when a recipient opens the email
clicked: when a recipient clicks a link within the email message
unsubscribed: when a recipient clicks the unsubscribe link/button.
abuse: when a recipient marks the email as spam.
4
Confidential Falconide Webhooks Integration Guide Version 1.1
3. How to Configure Webhooks
You can configure webhooks from your Falconide account. To configure, perform the following steps:
a. Log in to your Falconide account.
b. Go to Settings -> API.
c. Click Webhooks under the API menu.
d. Select the data sending type from the options: GET,POST, JSON and BULK JSON.
e. You can either choose to have one global API that sends notifications for all the events, or you can define custom APIs for different events.
f. Whichever option you choose, enter a valid Call back URL where Falconide can POST the event data.
5
Confidential Falconide Webhooks Integration Guide Version 1.1
g. If you select custom APIs, then select the parameters that you want to receive for each API.
h. If you want to test the Webhook call, click Test.
Sample of JSON Bulk API Push:
[
{"TRANSID":"14507226013384557","X-APIHEADER":"1234","RESPONSE":"smtp;250 2.0.0 OK 1450791482
n83si34501442qhn.97 -
gsmtp","EVENT":"sent","RCPTID":"19556","EMAIL":"xxxxxxxxxx@gmail.com","TIMESTAMP":"1450791482"},
{"TRANSID":"14507226013383534","X-APIHEADER":"1234","RESPONSE":"smtp;250 2.0.0 OK 1450791482
v72si34546256qka.96 -
gsmtp","EVENT":"sent","RCPTID":"19556","EMAIL":"xxxxxxxxxx@gmail.com","TIMESTAMP":"1450791482"},
{"TRANSID":"14507226013385581","X-APIHEADER":"1234","RESPONSE":"smtp;250 2.0.0 OK 1450791482
m11si34606295qgd.21 -
gsmtp","EVENT":"sent","RCPTID":"19556","EMAIL":"xxxxxxxxxx@gmail.com","TIMESTAMP":"1450791482"}
]
Important:
1. If your system is behind a firewall that blocks access to all traffic except for certain domains, then you must grant access to Falconide.com so that the Webhooks
can function. You need to allow 202.162.242.179/255 range of IPs on your network.
2. Your Webhooks URLs should be set up to accept the POST requests coming from the Falconide server. When you provide the URL where you want Falconide to
POST the data for events, a quick check is done through HEAD request (not POST) to ensure that the URL exists.
If the URL doesn't exist or returns something other than a 200 HTTP response to the HEAD request, Falconide will fallback and attempt a POST request. The POST is
the same type of POST as a Falconide Webhook, except that the parameter is an empty array.
6
Confidential Falconide Webhooks Integration Guide Version 1.1
4. Events Data
Here is a sample data for each event showing the actual fields that are returned in the HTTP POST:
Parameters Description Supported Events
TRANSID The unique transaction ID that Falconide assigns to each sent All
email
EMAIL The email address of the recipient All
EVENT Type of Event: sent/ dropped/ invalid/ bounced/ opened/ All
clicked/ unsubscribed/ abuse
sent, dropped, invalid,
RESPONSE Response received from the end server: Delivery Logs, Bounce
bounce
reason, reason for drop (blacklisted user / already unsubscribed)
X-APIHEADER Information passed by you in the X-APIHEADER, during the time All
of email sent
TIMESTAMP Unix Timestamp of the occurrence of the event All
opened, clicked,
USERAGENT Detailed information about the browser from where a specific
unsubscribed, abuse
event is initiated
IPADDRESS opened, clicked,
IP address of the device from which the recipient responds
unsubscribed, abuse
SUBJECT Subject of the email All
FROMADDRESS From address which is used in email at the time of email sent All
7
Confidential Falconide Webhooks Integration Guide Version 1.1
Here are samples of values that are returned for the events:
Events Sample values
TRANSID EMAIL RESPONSE X- TIMESTAMP USERAGENT IPADDRES SUBJECT FROM BOUNC BOU BOU URL
APIHEADER S ADDRESS E_TYPE NCE_ NCE_
REAS REAS
ON ONID
sent 198987967526 test@exampl 175.158.64.39-> ACC12312 1358402419 NA NA Thank info@ex
e.com 250 2.0.0 OK you ample.co
k2si444142... email m
dropped 198987967526 test@exampl Blacklisted user / ACC12312 1358402419 NA NA Thank info@ex
e.com Already you ample.co
unsubscribed email m
invalid 198987967526 test@exampl Invalid Email ACC12312 1358402419 NA NA Thank info@ex
e.com Address you ample.co
email m
bounced 198987967556 test@exampl ACC12311 1358402419 NA NA Thank info@ex HARDB 550 342
e.com you ample.co OUNCE 5.1.1
email m /SOFTB The
OUNCE email
accou
nt
does
not
exist
opened 1989867556 test@exampl NA ACC12311 1358402419 Mozilla/5.0 209.167.1 Thank info@ex
e.com (Macintosh; 8.19 you ample.co
Intel email m
AppleWebKi
t/537.36
clicked 1982796 test@exampl NA BC12311 1358402419 Mozilla/5.0 209.167.1 Thank info@ex http://www.
e.com (Macintosh; 8.19 you ample.co wearewater.
AppleWebKi email m org/index.ph
t/537.36 p
unsubscr 1987556 test@exampl NA AC12311 1358402419 Mozilla/5.0 209.167.1 Thank info@ex
ibed e.com (Macintosh; 8.19 you ample.co
Intel email m
AppleWebKi
t/537.36
8
Confidential Falconide Webhooks Integration Guide Version 1.1
abuse 198987967556 test@gmail.c ACC12311 1358402419 NA NA Thankyo info@ex
om u email ample.co
m
5. How to collect the event data?
To collect the event data posted by Webhooks, you need to write a script in any programming language of your choice. This is language as well as platform
independent. Here is a sample PHP script:
<?php
$fp =fopen('/tmp/weblog.txt','a');
foreach($_POST as $key=>$val) {
fwrite($fp,"$key=>$val");
}
fwrite($fp,"\n");
fclose($fp);
?>
Sample Function to convert Timestamp into Date:
echo date('m/d/Y', 1299446702);
6. Track your Webhooks
All the Webhook calls are logged in real-time. You can view/download the reports from the Reports section in the Falconide panel.
7. Support
If you have a question, call +91-(22)-66628081
You can also drop a mail to support@falconide.com
