Webhooks
Posted on Tuesday, January 29th, 2013.
Mobilize Mail supports Webhooks for the following events:
Events Supported
Subscriber Confirmation
When the subscriber has clicked the activation url within the confirmation email to confirm their subscription.
Subscriber Change Preferences
When a subscriber has updated their subscription details.
Subscriber Unsubscribe
When a subscriber has unsubscribed or a hard bounce has been generated.
Webhook Payload Format
The webhook generates a HTTP POST payload with the standard key/value pairs of the subscribers details including email address, subscriber hash, subscriber fields and mailing list subscription details.
For each payload the following fields are present:
“type” – this is the event linked to the webhook for example “subscribe” for subscriber confirmation.
“key” – this is the secret key that was added to the signup form webhooks section. The secret key is sent within the payload so the end point code can validate the payload.
“fired_at” – the GMT date/time of the webhook being executed.
Subscriber Confirmation
For Subscriber Confirmation all subscriber fields linked to the signup form used by the subscriber to subscribe will be listed and the subscribers value as well as all mailing lists linked to the signup form. If a subscriber is subscribed to a mailing list then the value will be “1” if the subscriber is not subscribed to a mailing list then the value is “0”.
Below is an example of a typical Subscriber Confirmation payload.
"type":"subscribe"
"key":"4353"
"fired_at":"2013-01-28 20:52",
"data[subscriber_hash]":"5106e4bcdbf6e"
"data[email]":"[email protected]"
"data[FirstName]":"Bob"
"data[LastName]":"Smith"
"mailinglist[50f74dcf4a900]": 1
Subscriber Change Preferences
For Subscriber Change Preferences all subscriber fields linked to the signup form used by the subscriber to subscribe will be listed and the subscribers value as well as all mailing lists linked to the signup form. If a subscriber is subscribed to a mailing list then the value will be “1” if the subscriber is not subscribed to a mailing list then the value is “0”.
Below is an example of a typical Subscriber Confirmation payload.
"type":"subscribe"
"key":"4353"
"fired_at":"2013-01-28 20:52",
"data[subscriber_hash]":"5106e4bcdbf6e"
"data[email]":"[email protected]"
"data[FirstName]":"Bob"
"data[LastName]":"Smith"
"mailinglist[50f74dcf4a900]": 1
Subscriber Unsubscribe
For Subscriber Unsubscribe all subscriber fields linked to the signup form used by the subscriber to subscribe will be listed and the subscribers value as well as all mailing lists linked to the signup form. If a subscriber is subscribed to a mailing list then the value will be “1” if the subscriber is not subscribed to a mailing list then the value is “0”.
Below is an example of a typical Subscriber Confirmation payload.
"type":"subscribe"
"key":"4353"
"fired_at":"2013-01-28 20:52",
"data[subscriber_hash]":"5106e4bcdbf6e"
"data[email]":"[email protected]"
"data[FirstName]":"Bob"
"data[LastName]":"Smith"
"mailinglist[50f74dcf4a900]": 1
NOTE: If the subscriber generated a hard bounce then the payload will include the following extra data:
“bounce_reason” – this field will supply the bounce code generated that caused the subscriber to be removed from all mailing lists.
Configuring Webhooks for Subscriber Events
All webhooks which deal with subscriber events are located within a signup forms configuration. To configure a webhook for a subscriber event follow the steps below.
1) Create or edit an existing signup form.
2) Click the “Webhooks” tab.
3) The tab will display the following fields:
A) Security Key – enter in a secret “key” such as a hash. The system will send this value in every payload. This enables the end point to validate the payload.
B) Confirmed Subscription POST url – enter in the URL that the system will HTTP POST the payload to when a subscriber successfully subscribes using the signup form. “Successfully subscribes” is when the subscriber clicks on the activation link within the confirmation email to confirm their subscription.
C) Change Preferences POST url – enter in the URL that the system will HTTP POST the payload to when a subscriber changes their subscription record via the signup form.
D) Unsubscribe POST url – enter in the URL that the system will HTTP POST the payload to when a subscriber unsubscribes via the signup form.
4) Click the “Save” button to save the changes.
Testing Webhooks
To test a webhook we recommend using RequestBin which provides a handy free service which allows you to test the payload of the webhook.
Comments are closed.