Overview

Integration

User guide

API reference

Webhooks

Webhooks API

Lets you manage webhooks for a specific Transactional or Broadcast Message Stream.

List webhooks #

get

/webhooks

Request headers

Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/webhooks?MessageStream=outbound" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Querystring parameters

MessageStream

Filter by message stream. If no stream is provided, will return all webhooks for the server. If a non existing stream is provided, an error is thrown instead of an empty webhooks array.

Response

Webhooks array

A list of webhooks associated with this server.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{ 
    "Webhooks": [
        {
            "ID": 1234567, 
            "Url": "http://www.example.com/webhook-test-tracking",
            "MessageStream": "outbound",
            "HttpAuth":{ 
                "Username": "user",
                "Password": "pass"
            },
            "HttpHeaders":[
                {
                    "Name": "name",
                    "Value": "value"
                }
            ],
            "Triggers": { 
                "Open":{ 
                    "Enabled": true,
                    "PostFirstOpenOnly": false
                },
                "Click":{ 
                    "Enabled": true
                },
                "Delivery":{ 
                    "Enabled": true
                },
                "Bounce":{ 
                    "Enabled": false,
                    "IncludeContent": false
                },
                "SpamComplaint":{ 
                    "Enabled": false,
                    "IncludeContent": false
                },
                "SubscriptionChange": {
                    "Enabled": true
                }
            }
        },
        {
            "ID": 1234568, 
            "Url": "http://www.example.com/webhook-test-bounce",
            "MessageStream": "outbound",
            "HttpAuth":{ 
                "Username": "user",
                "Password": "pass"
            },
            "HttpHeaders":[
                {
                    "Name": "name",
                    "Value": "value"
                }
            ],
            "Triggers": { 
                "Open":{ 
                    "Enabled":false,
                    "PostFirstOpenOnly":false
                },
                "Click":{ 
                    "Enabled": false
                },
                "Delivery":{ 
                    "Enabled": false
                },
                "Bounce":{ 
                    "Enabled" :true,
                    "IncludeContent": false
                },
                "SpamComplaint":{ 
                    "Enabled": false,
                    "IncludeContent": false
                },
                "SubscriptionChange": {
                    "Enabled": false
                }
            }
        }

    ]
}

Get a webhook #

get

webhooks/{Id}

Request headers

Accept required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/webhooks/{Id}" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Postmark-Server-Token: server token"

Response

ID integer

ID of webhook.
Url string

Your webhook URL.
MessageStream string

The stream this webhook is associated with.
HttpAuth object

Optional. HTTP Auth username and password.
Username string

If present, HTTP Auth username.
Password string

If present, HTTP Auth password.
HttpHeaders array

Optional. List of custom headers included.
Name string

If present, name of HTTP header.
Value string

If present, value of HTTP header.
Triggers object

List of different possible triggers a webhook can be enabled/disabled for.
Open object

List of open webhook details.
Enabled boolean

Specifies whether or not open webhook is enabled.
PostFirstOpenOnly boolean

If enabled, open webhook will only POST on first open.
Click object

List of click webhook details.
Enabled boolean

Specifies whether or not click webhook is enabled.
Delivery object

List of delivery webhook details.
Enabled boolean

Specifies whether or not delivery webhook is enabled.
Bounce object

List of bounce webhook details.
Enabled boolean

Specifies whether or not bounce webhook is enabled.
IncludeContent boolean

Specifies whether or not the full content of the email bounce is included in webhook POST.
SpamComplaint object

List of spam complaint webhook details.
Enabled boolean

Specifies whether or not spam complaint webhook is enabled.
IncludeContent boolean

Specifies whether or not the full content of the spam complaint is included in webhook POST.
SubscriptionChange object

List of subscription change webhook details.
Enabled boolean

Specifies whether or not subscription change webhook is enabled.

Example response

{
    "ID": 1234567, 
    "Url": "http://www.example.com/webhook-test-tracking",
    "MessageStream": "outbound",
    "HttpAuth":{ 
        "Username": "user",
        "Password": "pass"
    },
    "HttpHeaders":[
        {
            "Name": "name",
            "Value": "value"
        }
    ],
    "Triggers": { 
        "Open":{ 
            "Enabled": true,
            "PostFirstOpenOnly": false
        },
        "Click":{ 
            "Enabled": true
        },
        "Delivery":{ 
            "Enabled": true
        },
        "Bounce":{ 
            "Enabled": false,
            "IncludeContent": false
        },
        "SpamComplaint":{ 
            "Enabled": false,
            "IncludeContent": false
        },
        "SubscriptionChange": {
            "Enabled": true
        }
    }
}

Create a webhook #

post

/webhooks

Request headers

Accept required

application/json
Content-Type required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/webhooks" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: server token" \
  -d '{
        "Url": "http://www.example.com/webhook-test-tracking",
            "MessageStream": "outbound",
            "HttpAuth":{ 
                "Username": "user",
                "Password": "pass"
            },
            "HttpHeaders":[
                {
                    "Name": "name",
                    "Value": "value"
                }
            ],
            "Triggers": { 
                "Open":{ 
                    "Enabled": true,
                    "PostFirstOpenOnly": false
                },
                "Click":{ 
                    "Enabled": true
                },
                "Delivery":{ 
                    "Enabled": true
                },
                "Bounce":{ 
                    "Enabled": false,
                    "IncludeContent": false
                },
                "SpamComplaint":{ 
                    "Enabled": false,
                    "IncludeContent": false
                },
                "SubscriptionChange": {
                    "Enabled": false
            }
            }
      }'

Body format

Url string required

Your webhook URL.
MessageStream string

The stream this webhook is associated with. If no MessageStream is provided, the default transactional stream outbound will be used.
HttpAuth object

Optional. Custom HTTP Auth username/password pairs
HttpHeaders array

Optional. Custom HTTP Headers name/value pairs.
Triggers object

List of different webhooks events to enable.
Open object

Listing for if the Open webhook is enabled/disabled. Webhook will only post on first open if PostFirstOpenOnly is enabled.
Click object

Listing for if the Click webhook is enabled/disabled.
Delivery object

Listing for if the Delivery webhook is enabled/disabled.
Bounce object

Listing for if the Bounce webhook is enabled/disabled. Webhook will send full bounce content if IncludeContent is enabled.
SpamComplaint object

Listing for if the Spam webhook is enabled/disabled. Webhook will send full spam content if IncludeContent is enabled.
SubscriptionChange object

Listing for if the Subscription Change webhook is enabled/disabled.

Example body format

{
    "ID": 1234567, 
    "Url": "http://www.example.com/webhook-test-tracking",
    "MessageStream": "outbound",
    "HttpAuth":{ 
        "Username": "user",
        "Password": "pass"
    },
    "HttpHeaders":[
        {
            "Name": "name",
            "Value": "value"
        }
    ],
    "Triggers": { 
        "Open":{ 
            "Enabled": true,
            "PostFirstOpenOnly": false
        },
        "Click":{ 
            "Enabled": true
        },
        "Delivery":{ 
            "Enabled": true
        },
        "Bounce":{ 
            "Enabled": false,
            "IncludeContent": false
        },
        "SpamComplaint":{ 
            "Enabled": false,
            "IncludeContent": false
        },
        "SubscriptionChange": {
            "Enabled": false
        }
    }
}

Response

ID integer

ID of webhook.
Url string

Your webhook URL.
MessageStream string

The stream this webhook is associated with.
HttpAuth object

HTTP Auth username and password.
Username string

If present, HTTP Auth username.
Password string

If present, HTTP Auth password.
HttpHeaders array

List of custom headers included.
Name string

If present, name of HTTP header.
Value string

If present, value of HTTP header.
Triggers object

List of different possible triggers a webhook can be enabled/disabled for.
Open object

List of open webhook details.
Enabled boolean

Specifies whether or not open webhook is enabled.
PostFirstOpenOnly boolean

If enabled, open webhook will only POST on first open.
Click object

List of click webhook details.
Enabled boolean

Specifies whether or not click webhook is enabled.
Delivery object

List of delivery webhook details.
Enabled boolean

Specifies whether or not delivery webhook is enabled.
Bounce object

List of bounce webhook details.
Enabled boolean

Specifies whether or not bounce webhook is enabled.
IncludeContent boolean

Specifies whether or not the full content of the email bounce is included in webhook POST.
SpamComplaint object

List of spam complaint webhook details.
Enabled boolean

Specifies whether or not spam complaint webhook is enabled.
IncludeContent boolean

Specifies whether or not the full content of the spam complaint is included in webhook POST.
SubscriptionChange object

List of subscription change webhook details.
Enabled boolean

Specifies whether or not subscription change webhook is enabled.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ID": 1234567, 
    "Url": "http://www.example.com/webhook-test-tracking",
    "MessageStream": "outbound",
    "HttpAuth":{ 
        "Username": "user",
        "Password": "pass"
    },
    "HttpHeaders":[
        {
            "Name": "name",
            "Value": "value"
        }
    ],
    "Triggers": { 
        "Open":{ 
            "Enabled": true,
            "PostFirstOpenOnly": false
        },
        "Click":{ 
            "Enabled": true
        },
        "Delivery":{ 
            "Enabled": true
        },
        "Bounce":{ 
            "Enabled": false,
            "IncludeContent": false
        },
        "SpamComplaint":{ 
            "Enabled": false,
            "IncludeContent": false
        },
        "SubscriptionChange": {
            "Enabled": false
        }
    }
}

Edit a webhook #

put

webhooks/{Id}

Request headers

Accept required

application/json
Content-Type required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/webhooks/{Id}" \
  -X PUT \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: server token" \
  -d '{ 
        "Url": "http://www.example.com/webhooks",
        "HttpAuth":{ 
            "Username": "user",
            "Password": "pass"
        },
        "HttpHeaders":[
            {
                "Name": "name",
                "Value": "value"
            }
        ],
        "Triggers": { 
            "Open":{ 
                "Enabled": true,
                "PostFirstOpenOnly": false
            },
            "Click":{ 
                "Enabled": true
            },
            "Delivery":{ 
                "Enabled": true
            },
            "Bounce":{ 
                "Enabled": true,
                "IncludeContent": false
            },
            "SpamComplaint":{ 
                "Enabled": true,
                "IncludeContent": false
            },
            "SubscriptionChange": {
                "Enabled": false
            }
        }
    }'

Body format

Url string

Optional. Your new webhook URL.
HttpAuth object

Optional. Add new Custom HTTP Auth username/password pairs.
HttpHeaders array

Optional. Add new Custom HTTP Headers name/value pairs.
Triggers object

Optional. List of different webhooks events to enable/disable. If only click is provided, the other events will not changed. If no triggers are provided there’ll be no change.
Open object

Listing for if the Open webhook is enabled/disabled. Webhook will only post on first open if PostFirstOpenOnly is enabled.
Click object

Listing for if the Click webhook is enabled/disabled.
Delivery object

Listing for if the Delivery webhook is enabled/disabled.
Bounce object

Listing for if the Bounce webhook is enabled/disabled. Webhook will send full bounce content if IncludeContent is enabled.
SpamComplaint object

Listing for if the Spam webhook is enabled/disabled. Webhook will send full spam content if IncludeContent is enabled.
SubscriptionChange object

Listing for if the Subscription Change webhook is enabled/disabled.

Example body format

{ 
        "Url": "http://www.example.com/webhooks",
        "HttpAuth":{ 
            "Username": "user",
            "Password": "pass"
        },
        "HttpHeaders":[
            {
                "Name": "name",
                "Value": "value"
            }
        ],
        "Triggers": { 
            "Open":{ 
                "Enabled": true,
                "PostFirstOpenOnly": false
            },
            "Click":{ 
                "Enabled": true
            },
            "Delivery":{ 
                "Enabled": true
            },
            "Bounce":{ 
                "Enabled": true,
                "IncludeContent": false
            },
            "SpamComplaint":{ 
                "Enabled": true,
                "IncludeContent": false
            },
            "SubscriptionChange": {
                "Enabled": false
            }
        }
}

Response

ID integer

ID of webhook.
Url string

Your webhook URL.
MessageStream string

The stream this webhook is associated with.
HttpAuth object

HTTP Auth username and password.
Username string

If present, HTTP Auth username.
Password string

If present, HTTP Auth password.
HttpHeaders array

List of custom headers included.
Name string

If present, name of HTTP header.
Value string

If present, value of HTTP header.
Triggers object

List of different possible triggers a webhook can be enabled/disabled for.
Open object

List of open webhook details.
Enabled boolean

Specifies whether or not open webhook is enabled.
PostFirstOpenOnly boolean

If enabled, open webhook will only POST on first open.
Click object

List of click webhook details.
Enabled boolean

Specifies whether or not click webhook is enabled.
Delivery object

List of delivery webhook details.
Enabled boolean

Specifies whether or not delivery webhook is enabled.
Bounce object

List of bounce webhook details.
Enabled boolean

Specifies whether or not bounce webhook is enabled.
IncludeContent boolean

Specifies whether or not the full content of the email bounce is included in webhook POST.
SpamComplaint object

List of spam complaint webhook details.
Enabled boolean

Specifies whether or not spam complaint webhook is enabled.
IncludeContent boolean

Specifies whether or not the full content of the spam complaint is included in webhook POST.
SubscriptionChange object

List of subscription change webhook details.
Enabled boolean

Specifies whether or not subscription change webhook is enabled.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{ 
        "ID": 1234567,
        "Url": "http://www.example.com/webhooks",
        "MessageStream": "outbound",
        "HttpAuth":{ 
            "Username": "user",
            "Password": "pass"
        },
        "HttpHeaders":[
            {
                "Name": "name",
                "Value": "value"
            }
        ],
        "Triggers": { 
            "Open":{ 
                "Enabled": true,
                "PostFirstOpenOnly": false
            },
            "Click":{ 
                "Enabled": true
            },
            "Delivery":{ 
                "Enabled": true
            },
            "Bounce":{ 
                "Enabled": true,
                "IncludeContent": false
            },
            "SpamComplaint":{ 
                "Enabled": true,
                "IncludeContent": false
            },
            "SubscriptionChange": {
                "Enabled": false
            }
        }
}

Delete a webhook #

delete

/webhooks/{Id}

Request headers

Accept required

application/json
Content-Type required

application/json
X-Postmark-Server-Token required

This request requires server level privileges. This token can be found from the API Tokens tab under your Postmark server.

Example request with curl

curl "https://api.postmarkapp.com/webhooks/{Id}" \
  -X DELETE \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: server token"

Response

ErrorCode integer

API Error Codes
Message string

Associated success or error message.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ErrorCode": 0,
    "Message": "Webhook 1234 removed."
}