Webhooks

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.

Event Types

Webhook events can be sent whenever one of the following events occur:

• Delivered Message (delivered)
• Failure Message (failed)
• Bounced Message (bounced)

These events require open and click tracking to be enabled:

• Message Opened (opened)
• Link Clicked (clicked)

Additional events may be provided for hard unsubscribe requests made through the PostageApp opt-out portal:

• Unsubscribed (unsubscribed)

Where the destination domain provides a Spam Feedback Loop service, spam reports will be processed and forwarded:

• Spam Complaint (spammed)

Payload Formats

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.

JSON (Version 1.0)

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.

URL-Encoded (Option 1)

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.