Postmark
Postmark API

Webhooks

Configure, verify and monitor webhooks that push delivery, bounce, spam complaint, open, click and subscription change events to your application.


List webhooks

GET
https://api.postmarkapp.com
/webhooks

Lists the webhooks on the server, optionally filtered by message stream. Passing a stream that does not exist returns an error rather than an empty list.

List webhooks › query Parameters

MessageStream
​string

Filter by message stream ID. When omitted, webhooks for all streams on the server are returned.

List webhooks › Responses

The webhooks.

A list of webhooks.
​Webhook[] · required

Webhooks on the server (or the filtered stream).

Example: [{"ID":1234567,"Url":"https://www.example.com/webhook-test-tracking","MessageStream":"outbound","Status":"verified","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}}}]

Create a webhook

POST
https://api.postmarkapp.com
/webhooks

Creates a webhook on a Transactional or Broadcast stream. By default Postmark verifies the endpoint by sending a test for every enabled event; each must return HTTP 200 or nothing is saved and you receive 422 (error code 1364) with per-event results. Set Verify to false to save an unverified webhook, which receives no events until you call the verify endpoint.

The callbacks of this operation describe the payloads Postmark posts to your URL. Postmark does not sign webhooks; protect your endpoint with HTTP Basic Auth (HttpAuth), custom headers and IP allowlisting.

Create a webhook › Request Body

Webhook to create.
Url
​string · uri · required

URL Postmark posts events to.

Example: https://www.example.com/webhook-test-tracking
MessageStream
​string

Stream to attach the webhook to. Defaults to outbound. Cannot be an inbound or archived stream.

Example: outbound
​WebhookHttpAuth

HTTP Basic Auth credentials Postmark sends with each webhook request.

​CustomHeader[]

Custom HTTP headers to send with each request.

Example: [{"Name":"X-Custom-Header","Value":"custom-value"}]
​WebhookTriggers

Events a webhook receives. In edit requests, triggers you omit are left unchanged.

Verify
​boolean

Test the endpoint for each enabled event before saving. Defaults to true. Set false to save unverified; the webhook receives no events until verified.

Example: true

Create a webhook › Responses

The created webhook.

A webhook configuration.
ID
​integer

Unique ID of the webhook. Field of Webhook.

Example: 1234567
Url
​CreateWebhookRequest/properties/Url · uri

URL Postmark posts events to.

Example: https://www.example.com/webhook-test-tracking
MessageStream
​string

Message stream the webhook belongs to.

Example: outbound
​WebhookHttpAuth

HTTP Basic Auth credentials Postmark sends with each webhook request.

​CustomHeader[]

Custom HTTP headers sent with each request.

Example: [{"Name":"X-Custom-Header","Value":"custom-value"}]
​WebhookTriggers

Events a webhook receives. In edit requests, triggers you omit are left unchanged.

Status
​string · enum

Verification status. An unverified webhook receives no events until it passes verification.

Enum values:
verified
unverified
Example: verified

Get a webhook

GET
https://api.postmarkapp.com
/webhooks/{webhookId}

Returns a webhook configuration.

Get a webhook › path Parameters

webhookId
​integer · required

Unique ID of the webhook.

Get a webhook › Responses

The webhook.

A webhook configuration.
ID
​integer

Unique ID of the webhook. Field of Webhook.

Example: 1234567
Url
​CreateWebhookRequest/properties/Url · uri

URL Postmark posts events to.

Example: https://www.example.com/webhook-test-tracking
MessageStream
​string

Message stream the webhook belongs to.

Example: outbound
​WebhookHttpAuth

HTTP Basic Auth credentials Postmark sends with each webhook request.

​CustomHeader[]

Custom HTTP headers sent with each request.

Example: [{"Name":"X-Custom-Header","Value":"custom-value"}]
​WebhookTriggers

Events a webhook receives. In edit requests, triggers you omit are left unchanged.

Status
​string · enum

Verification status. An unverified webhook receives no events until it passes verification.

Enum values:
verified
unverified
Example: verified

Edit a webhook

PUT
https://api.postmarkapp.com
/webhooks/{webhookId}

Updates a webhook. Changing the URL or enabling more events re-verifies the endpoint before saving; on failure the request returns 422 (error code 1364) and the webhook is unchanged. Set Verify to false to save without testing. The ID and MessageStream cannot be changed.

Edit a webhook › path Parameters

webhookId
​integer · required

Unique ID of the webhook.

Edit a webhook › Request Body

Webhook fields to change. Editing re-verifies the webhook unless `Verify` is `false`.
Url
​CreateWebhookRequest/properties/Url · uri

URL Postmark posts events to.

Example: https://www.example.com/webhook-test-tracking
​WebhookHttpAuth

HTTP Basic Auth credentials Postmark sends with each webhook request.

​CustomHeader[]

Custom HTTP headers to send with each request. Field of EditWebhookRequest.

Example: [{"Name":"X-Custom-Header","Value":"custom-value"}]
​WebhookTriggers

Events a webhook receives. In edit requests, triggers you omit are left unchanged.

Test the endpoint for each enabled event before saving. Defaults to true. Set false to save unverified; the webhook receives no events until verified.

Example: true

Edit a webhook › Responses

The updated webhook.

A webhook configuration.
ID
​integer

Unique ID of the webhook. Field of Webhook.

Example: 1234567
Url
​CreateWebhookRequest/properties/Url · uri

URL Postmark posts events to.

Example: https://www.example.com/webhook-test-tracking
MessageStream
​string

Message stream the webhook belongs to.

Example: outbound
​WebhookHttpAuth

HTTP Basic Auth credentials Postmark sends with each webhook request.

​CustomHeader[]

Custom HTTP headers sent with each request.

Example: [{"Name":"X-Custom-Header","Value":"custom-value"}]
​WebhookTriggers

Events a webhook receives. In edit requests, triggers you omit are left unchanged.

Status
​string · enum

Verification status. An unverified webhook receives no events until it passes verification.

Enum values:
verified
unverified
Example: verified

Delete a webhook

DELETE
https://api.postmarkapp.com
/webhooks/{webhookId}

Deletes a webhook.

Delete a webhook › path Parameters

webhookId
​integer · required

Unique ID of the webhook.

Delete a webhook › Responses

The webhook was deleted.

Generic response returned by operations that only report a result code and message.
ErrorCode
​integer · required

Postmark API error code. 0 means the request succeeded. See the API error code table in the API description.

Example: 0
Message
​string · required

Human-readable result of the request.

Example: OK

Get webhook statistics

GET
https://api.postmarkapp.com
/webhooks/{webhookId}/statistics

Returns delivery statistics for a webhook over a fixed rolling 24-hour window. Call once per webhook if a stream has several.

Get webhook statistics › path Parameters

webhookId
​integer · required

Unique ID of the webhook.

Get webhook statistics › Responses

Webhook delivery statistics.

Webhook delivery statistics over a rolling 24-hour window.
WebhookId
​integer

ID of the webhook.

Example: 12345
ServerId
​integer

ID of the server. Field of WebhookStatistics.

Example: 67890
MessageStreamId
​Webhook/properties/MessageStream

Message stream the webhook belongs to.

Example: outbound
Url
​string · uri

Webhook URL.

Example: https://example.com/webhook
​object

Verification status per trigger.

Example: {"Bounce":"unverified","Delivery":"verified"}
​object

The window the statistics cover.

Example: {"StartTime":"2026-10-05T18:00:00Z","EndTime":"2026-10-06T18:00:00Z","Hours":24}
​WebhookMetrics

Delivery metrics for a webhook over the window.

​object

The same metrics broken out per trigger (for example Bounce, Delivery).

Example: {"key":{"TotalRequests":1000,"SuccessCount":950,"FailureCount":50,"RetryCount":20,"SuccessRate":95,"SlowCount":50,"VerySlowCount":10,"AverageTerminalResponseTimeMs":255,"AverageRetryResponseTimeMs":450}}

Verify a webhook

POST
https://api.postmarkapp.com
/webhooks/{webhookId}/verify

Tests the webhook endpoint for each enabled event. If every event returns HTTP 200 the webhook is marked verified; otherwise it is marked unverified and receives no events until it passes. A 200 response means the check ran, not that it passed; inspect Success and Results.

Verify a webhook › path Parameters

webhookId
​integer · required

Unique ID of the webhook.

Verify a webhook › Responses

The verification result.

Outcome of testing a webhook endpoint. A 200 HTTP status on the verify call means the check ran, not that it passed; inspect `Success`.
Id
​integer · required

ID of the webhook that was tested.

Example: 354118
Url
​string · uri · required

URL that was tested.

Example: https://www.example.com/webhook
Success
​boolean · required

true only if every enabled event returned HTTP 200.

Example: true
​object[] · required

Per-event results.

Example: [{"TriggerType":"Open","Success":true,"StatusCode":200,"Message":"Remote server returned an HTTP status code of 200."}]
Message
​string · required

Summary of the verification.

Example: 5/5 triggers verified successfully