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_time | A datetime stamp showing the server time that the bounce was processed. |
| The email address being bounced. | |
| user_id | The user ID in Pinpointe that corresponds to the account through which this webhook is processed. |
| subscriber_id | The subscriber ID in Pinpointe that corresponds to the email address this webhook is processing. |
| list_id | The list ID in Pinpointe that corresponds to the database from which this email / subscriber ID belong to. |
| bounce_category | Varies by responding bounce server. Typically contains the bounce code. |
| bounce_message | Varies by responding bounce server. Typically contains information about what kind of bounce the server processed i.e. bad-mailbox, etc. |
| bounce_type | Whether hard or soft bounce. |
| bounce_time | Unix timestamp of the bounce. |
| source | The Pinpointe application URL from which the bounce webhook was processed through. |
| destination | The URL that should be receiving this webhook payload. |
| CRM-ID | If 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_time | A datetime stamp showing the server time that the unsubscribe was processed. |
| The email address being unsubscribed. | |
| user_name | The user name associated with the user ID. |
| user_id | The user ID in Pinpointe that corresponds to the account through which this webhook is processed. |
| list_ids | The list ID(s) in Pinpointe that corresponds to the database(s) from which this email / subscriber ID belong to. |
| tag_ids | The tag ID(s) in Pinpointe that corresponds to the lists(s) from which this email / subscriber ID has been assigned. |
| subscriber_id | The subscriber ID in Pinpointe that corresponds to the email address this webhook is processing. |
| global | Whether or not the unsubscribe event was a master unsubscribe. |
| source | The Pinpointe application URL from which the bounce webhook was processed through. |
| destination | The URL that should be receiving this webhook payload. |
| CRM-ID | If 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_time | A datetime stamp showing the server time that the campaign send job was initially processed. |
| user_id | The user ID in Pinpointe that corresponds to the account through which this webhook is processed. |
| job_status | The status of the campaign send job. Possible values are:
|
| job_id | The internal Pinpointe job ID assign to the send event. |
| job_type | The job type has two possible values:
|
| stat_id | The campaign stat ID associated with this send. This will not be assigned until the respective send has completely finished sending. |
| source | The Pinpointe application URL from which the bounce webhook was processed through. |
| destination | The URL that should be receiving this webhook payload. |