How to configure webhooks?

Configuring Webhooks


You can configure Webhooks from your PepiPost account. Here are the basic steps:
1. Login to your Pepipost account
2. Navigate to Settings
3. Click the Webhooks tab
4. Enter a valid Callback URL where PepiPost can POST the event data. As per your business requirement, you can configure Webhooks for all or selected categories of events (Refer the previous section on the list of supported events)

 

Security

Data Encryption

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.

What needs to be done at my end?

1. If your systems are behind a firewall that blocks access to all traffic except for certain domains then your network has to grant access to PepiPost.com, in order for the webhooks to function correctly, the administrators of your network will have to allow all the following range of IPs on your network:

  • 202.162.224.0/19

2. Your Webhooks URLs should be set up to accept the POST requests coming from our Pepipost server. When you provide the URL where you want PepiPost to POST the data for events, we'll do a quick check that the URL exists by using a HEAD request (not POST). If the URL doesn't exist or returns something other than a 200 HTTP response to the HEAD request, PepiPost will fallback and attempt a POST request. The POST will be the same type of POST as a PepiPost Webhook, except that the parameter will be an empty array.

How does Data Transmission happens?
When an event occurs that you have specified a callback URL for, Webhooks will send a HTTP POST request to the URL you've specified and it will do its best to deliver the events to your endpoint. But, if that URL is unavailable (does not return 200 HTTP response code) or takes too long to respond (more than 60 seconds), we'll cancel the request and the dispatcher will attempt several retries (with increasing interval) until the maximum retry limit of 5 is reached.

Retry increments
1. 15 minutes after the most recent failure
2. 45 minutes after the most recent failure
3. 90 minutes after the most recent failure
4. 1 hour after the most recent failure
5. 75 minutes after the most recent failure

Once the maximum retry limit is reached for a specific event, your hook call will be treated as failed and no further retries are allowed. Data shared over HTTP POST to your pre-configured Webhooks URL.

Event Data

Below is the sample data for each event which will show you the actual fields which were returned
in the HTTP POST:

Glossary:

Parameters Used Supported by Events Description
TRANSID All All assigns a Unique Transaction ID for each and every emails which were sent
EMAIL All Recipient’s Email ID
EVENT All Type of Event: delivered/ dropped/ invalid/ bounced/ opened/ clicked/ unsubscribed/ spam
RESPONSE delivered/ dropped/invalid/ bounce Response received from the end server like Delivery Logs, Bounce reason, reason for drop(blacklisted user / already unsubscribed)
X-APIHEADER All Information passed by you in the X-APIHEADER, during the time of email sent
TIMESTAMP All Unix Timestamp of the occurrence of the event
USERAGENT opened/ clicked/ unsubscribed/spam User agent contains the detailed information about the browser from where a specific event in initiated.
IPADDRESS opened/ clicked/unsubscribed/spam IP address of the device from where the recipient has responded.

 

1. Sent
Email has been successfully delivered to the receiving server:

Sample POST Output:

[  
  {  
    "TRANSID":"14652378013752608",
    "RCPTID":"0",
    "RESPONSE":"smtp;250 2.0.0 OK 1465276276 mo3si31128106wjb.147 - gsmtp",
    "EMAIL":"test@gmail.com",
    "TIMESTAMP":"1465276276",
    "CLIENTID":"10001",
    "FROMADDRESS":"info@mydomain.com",
    "EVENT":"sent",
    "MSIZE":"1216",
    "USERAGENT":"1216"
  }
]

 

2. Dropped
Users who have already unsubscribed in past or blacklisted because of hard bounce/Spam complaints will be treated as dropped. And, no further email communication is allowed on these types of ids.

Sample POST Output:

[  
  {  
    "TRANSID":"14652378021238672",
    "RCPTID":"0",
    "RESPONSE":"Recipient Dropped :: status not confirmed",
    "EMAIL":"sample@gmail.com",
    "TIMESTAMP":"1465300547",
    "CLIENTID":"10001",
    "FROMADDRESS":"info@mydomain.com",
    "EVENT":"dropped",
    "MSIZE":"575"
  }
]


3. Invalid
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.

Sample POST Output:

[  
  {  
    "TRANSID":"14652378021198302",
    "RCPTID":"",
    "RESPONSE":"Invalid Email Address",
    "EMAIL":"sampleuser@gmail..com",
    "TIMESTAMP":"1465300638",
    "CLIENTID":"10001",
    "FROMADDRESS":"info@mydomain.com",
    "EVENT":"invalid",
    "MSIZE":"16900"
  }
]

 

4. Bounced
Receiving server could not or would not accept message because of multiple reasons like receiving server is not reachable, email id doesn’t exists etc. All such reasons are a part of Hard Bounce which will lead to the blacklisting of that email id in Pepipost system. There are other set of bounces which are treated as Soft Bounce, e.g. Mailbox full. These are temporary bounces.

Sample POST Output:

Hard Bounce:

[  
  {  
    "TRANSID":"14652378014624064",
    "RCPTID":"0",
    "RESPONSE":"smtp;550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 z130si23626456iod.1",
    "BOUNCE_TYPE":"HARDBOUNCE",
    "EMAIL":"jdshfjhsdfjsdfsdfsdfhds@gmail.com",
    "TIMESTAMP":"1465277622",
    "BOUNCE_REASONID":"77",
    "CLIENTID":"10001",
    "BOUNCE_REASON":"email account that you tried to reach does not exist",
    "FROMADDRESS":"info@mydomain.com",
    "EVENT":"bounced",
    "MSIZE":"10",
    "USERAGENT":"10"
  }
]

Soft Bounce:

[  
  {  
    "TRANSID":"14652378014624064",
    "RCPTID":"0",
    "RESPONSE":"smtp;550 5.1.1 Mail box full",
    "BOUNCE_TYPE":"SOFTBOUNCE",
    "EMAIL":"test01@gmail.com",
    "TIMESTAMP":"1465277622",
    "BOUNCE_REASONID":"1099",
    "CLIENTID":"10001",
    "BOUNCE_REASON":"mail box full for the account you reached",
    "FROMADDRESS":"info@mydomain.com",
    "EVENT":"bounced",
    "MSIZE":"10",
    "USERAGENT":"10"
  }
]

 

5. Opened
Recipient has opened the email.

Sample POST Output:

[  
  {  
    "TRANSID":"14652378013752608",
    "RCPTID":"0",
    "RESPONSE":"",
    "EMAIL":"test@gmail.com",
    "TIMESTAMP":"1465276362",
    "CLIENTID":"10001",
    "FROMADDRESS":"info@mydomain.com",
    "EVENT":"opened",
    "MSIZE":"1216",
    "USERAGENT":"Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)",
    "IPADDRESS":"64.233.173.70"
  }
]


6. Clicked
Recipient has clicked on a link within the message. 

Sample POST Output:

[  
  {  
    "TRANSID":"14652378018802172",
    "RCPTID":"sampleuser@gmail.com",
    "RESPONSE":"",
    "EMAIL":"geniusdibya08@gmail.com",
    "TIMESTAMP":"1465299696",
    "CLIENTID":"10001",
    "FROMADDRESS":"info@mydomain.com",
    "EVENT":"clicked",
    "MSIZE":"19379",
    "USERAGENT":"Mozilla/5.0 (X11; Linux i686) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2564.116 Safari/537.36",
    "URL":"http://www.pepipost.com",
    "IPADDRESS":"11.11.11.16"
  }
]


7. Unsubscribed
Recipient clicked on the unsubscribe management link.

Sample POST Output:

[  
  {  
    "TRANSID":"14652378014983009",
    "RCPTID":"4",
    "RESPONSE":"",
    "EMAIL":"sampleuser@gmail.com",
    "TIMESTAMP":"1465278512",
    "CLIENTID":"10001",
    "FROMADDRESS":"info@mydomain.com",
    "EVENT":"unsubscribed",
    "MSIZE":"1718",
    "USERAGENT":"Mozilla/5.0 (X11; Linux i686) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2564.116 Safari/537.36",
    "IPADDRESS":"19.16.11.11"
  }
]



8. Spam
Recipient who marked the email as Spam

Sample POST Output:

[  
  {  
    "TRANSID":"14652378014983009",
    "RCPTID":"4",
    "RESPONSE":"",
    "EMAIL":"sampleuser@gmail.com",
    "TIMESTAMP":"1465278512",
    "CLIENTID":"10001",
    "FROMADDRESS":"info@mydomain.com",
    "EVENT":"spam",
    "MSIZE":"1718",
    "USERAGENT":"Mozilla/5.0 (X11; Linux i686) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2564.116 Safari/537.36",
    "IPADDRESS":"19.16.11.11"
  }
]