Webhook events are a facility to stream real-time information about email delivery and user engagement from PostageApp directly into applications.
These require an always-on HTTP or HTTPS receiver that can ingest JSON or URI-formatted POST payloads. Adding one of these to an existing application is usually quite straightforward.
Webhook events can be sent whenever one of the following events occur:
delivered
)failed
)bounced
)These events require open and click tracking to be enabled:
opened
)clicked
)Additional events may be provided for hard unsubscribe requests made through the PostageApp opt-out portal:
unsubscribed
)Where the destination domain provides a Spam Feedback Loop service, spam reports will be processed and forwarded:
spammed
)The payload can be delivered in one of two formats. The JSON payload type is the easiest to handle. The URL-Encoded form is provided for applications which do not easily ingest JSON-formatted payloads.
Delivered as a JSON payload with a Content-Type header of application/json
.
The structure resembles the following and varies depending on which variables
are defined in either the API call and/or the template(s) involved:
{
"event": "delivered",
"account": "example",
"project": "Example Project Name",
"recipient": "test@example.com",
"domain": "example.com",
"template": "main_template",
"timestamp": 1538849965,
"token": "Df8BUmR_UKk3rccU10cdVnnJtigUhkR5Au6n8d-poJJ1WX_eP_T5y4Zdng6E1QnLZpk=",
"signature": "efff14d0f321d5dd9b0b811b95d4d623086fa8fe9957dbc6fae5c5ab2e3122bd",
"message_headers": "[[\"x-example\",\"Example Header \"],[\"Subject\",\"Demo Email\"],[\"From\",\"Sender Example <sender@postageapp.com>\"]]",
"smtp_code": "SMTP_250",
"smtp_message": "2.0.0 OK 1569262700 b21si12459791iot.118 - gsmtp",
"example_variable": "Example Variable Value"
}
message_headers
contains a serialized payload describing the headers present
in JSON format.
Delivered via POST with Content-Type application/x-www-form-urlencoded
:
account=test&
domain=example.com&
event=delivered&
example_variable=Example+Variable+Value&
message_headers=%5B%5B%22x-example%22%2C%22Example+Header&+%7B%7Bexample_header_variable%7D%7D%22%5D%2C%5B%22Subject%22%2C%22Demo+Email%22%5D%2C%5B%22From%22%2C%22Sender+Example+%3Csender%40postageapp.com%3E%22%5D%5D&
project=Example+Project+Name&
recipient=test%40example.com&
signature=870df822af06537fd347044efb1b0d64be46106d704032bfabe8383c531b8973&
smtp_code=SMTP_250&
smtp_message=2.0.0+OK+1569262885+b3si15742426ion.94+-+gsmtp&
example_variable=Example+Variable+Value&
template=sample_child_template&
timestamp=1569262885&
token=mEzUhLii7KsTAlfuA4n2SLk-UWNVq5OIXYGf6abPuWWHn20f8OCmPvnlMjFk-YESdKM%3D
This is displayed on multiple lines for readability, but the actual payload has no newline characters.
message_headers
contains a serialized payload describing the headers present
in JSON format.