Overview 


Via webhooks, Pinpointe makes it possible to integrate your own application with your Pinpointe email service account when tracking your subscribers' unsubscribes, email address bounces, and your campaign sends.


A webhook is an API concept that allows a service (Pinpointe) to provide another application (such as a URL you specify) near-real time information as it is created. For example, if one of your subscribers elects to submit a request to unsubscribe from one of your email lists, this information is processed at Pinpointe and the webhook then makes a POST request to your specified URL with the unsubscribe event's details.


Unlike a "traditional" API call that must be initiated by the requester (you), a webhook is essentially always on and will send data whenever the triggering event occurs. Pinpointe currently offers webhooks for three events: Unsubscribes, Bounces. and Campaign Sends Each webhook delivers a JSON-formatted payload to the URL destination you provide.  


Implementing Webhooks in Your Pinpointe Account


Please contact Pinpointe Support to enable this feature. 

To reduce the time required for setup, please provide the URL to which you wish the webhook to make the POST request.


BOUNCES


An example of the JSON payload for a Bounce:




Description of attributes:


event_type"bounce"
event_timeA datetime stamp showing the server time that the bounce was processed.
emailThe email address being bounced.
user_idThe user ID in Pinpointe that corresponds to the account through which this webhook is processed.
subscriber_idThe subscriber ID in Pinpointe that corresponds to the email address this webhook is processing.
list_idThe list ID in Pinpointe that corresponds to the database from which this email / subscriber ID belong to.
bounce_categoryVaries by responding bounce server. Typically contains the bounce code.
bounce_messageVaries by responding bounce server. Typically contains information about what kind of bounce the server processed i.e. bad-mailbox, etc. 
bounce_typeWhether hard or soft bounce.
bounce_timeUnix timestamp of the bounce.
sourceThe Pinpointe application URL from which the bounce webhook was processed through.
destinationThe URL that should be receiving this webhook payload.
CRM-IDIf included, the CRM-ID custom field value for the subscriber ID.



UNSUBSCRIBES


PLEASE NOTE: Webhook triggering supports unsubscribes by contacts who choose to unsubscribe via link / form submission, and bounces where the system detects an actual bounce during an email delivery attempt. Webhooks do NOT trigger as the result of you, the user, changing a contact's status manually in the system via the contact edit page.


An example of the JSON payload for an Unsubscribe:



Description of attributes:


event_type"unsubscribe"
event_timeA datetime stamp showing the server time that the unsubscribe was processed.
emailThe email address being unsubscribed.
user_nameThe user name associated with the user ID.
user_idThe user ID in Pinpointe that corresponds to the account through which this webhook is processed.
list_idsThe list ID(s) in Pinpointe that corresponds to the database(s) from which this email / subscriber ID belong to.
tag_idsThe tag ID(s) in Pinpointe that corresponds to the lists(s) from which this email / subscriber ID has been assigned.
subscriber_idThe subscriber ID in Pinpointe that corresponds to the email address this webhook is processing.
globalWhether or not the unsubscribe event was a master unsubscribe. 
sourceThe Pinpointe application URL from which the bounce webhook was processed through.
destinationThe URL that should be receiving this webhook payload.
CRM-IDIf included, the CRM-ID custom field value for the subscriber ID.


CAMPAIGN SENDS


Several sub-events will trigger a Campaign Send webhook:

  • When the campaign is initially sent
  • When the campaign finished sending
  • When a campaign send event is paused before the send is completed
  • When a paused campaign send event is resumed
  • When a split test send event is started and completed
  • When the first batch of a batch send starts
  • When the final batch of the batch send finishes


An example of the JSON payload for the initial Campaign Send:


Description of attributes:


event_type"newsletter_send"
event_timeA datetime stamp showing the server time that the campaign send job was initially processed.
user_idThe user ID in Pinpointe that corresponds to the account through which this webhook is processed.
job_statusThe status of the campaign send job. Possible values are:
  • "started"
  • "paused"
  • "resumed"
  • "finished"
job_idThe internal Pinpointe job ID assign to the send event.
job_typeThe job type has two possible values:
  • "send"
  • "splittest"
stat_idThe campaign stat ID associated with this send. This will not be assigned until the respective send has completely finished sending. 
sourceThe Pinpointe application URL from which the bounce webhook was processed through.
destinationThe URL that should be receiving this webhook payload.