Webhooks
Configure, verify and monitor webhooks that push delivery, bounce, spam complaint, open, click and subscription change events to your application.
List 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.
query Parameters
MessageStreamFilter by message stream ID. When omitted, webhooks for all streams on the server are returned.
List webhooks › Responses
The webhooks.
Webhooks on the server (or the filtered stream).
Create a webhook
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
UrlURL Postmark posts events to.
MessageStreamStream to attach the webhook to. Defaults to outbound. Cannot be an inbound or archived stream.
HTTP Basic Auth credentials Postmark sends with each webhook request.
Custom HTTP headers to send with each request.
Events a webhook receives. In edit requests, triggers you omit are left unchanged.
VerifyTest the endpoint for each enabled event before saving. Defaults to true. Set false to save unverified; the webhook receives no events until verified.
Create a webhook › Responses
The created webhook.
IDUnique ID of the webhook. Field of Webhook.
UrlURL Postmark posts events to.
MessageStreamMessage stream the webhook belongs to.
HTTP Basic Auth credentials Postmark sends with each webhook request.
Custom HTTP headers sent with each request.
Events a webhook receives. In edit requests, triggers you omit are left unchanged.
StatusVerification status. An unverified webhook receives no events until it passes verification.
Get a webhook
Returns a webhook configuration.
path Parameters
webhookIdUnique ID of the webhook.
Get a webhook › Responses
The webhook.
IDUnique ID of the webhook. Field of Webhook.
UrlURL Postmark posts events to.
MessageStreamMessage stream the webhook belongs to.
HTTP Basic Auth credentials Postmark sends with each webhook request.
Custom HTTP headers sent with each request.
Events a webhook receives. In edit requests, triggers you omit are left unchanged.
StatusVerification status. An unverified webhook receives no events until it passes verification.
Edit a webhook
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.
path Parameters
webhookIdUnique ID of the webhook.
Edit a webhook › Request Body
UrlURL Postmark posts events to.
HTTP Basic Auth credentials Postmark sends with each webhook request.
Custom HTTP headers to send with each request. Field of EditWebhookRequest.
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.
Edit a webhook › Responses
The updated webhook.
IDUnique ID of the webhook. Field of Webhook.
UrlURL Postmark posts events to.
MessageStreamMessage stream the webhook belongs to.
HTTP Basic Auth credentials Postmark sends with each webhook request.
Custom HTTP headers sent with each request.
Events a webhook receives. In edit requests, triggers you omit are left unchanged.
StatusVerification status. An unverified webhook receives no events until it passes verification.
Delete a webhook
Deletes a webhook.
path Parameters
webhookIdUnique ID of the webhook.
Delete a webhook › Responses
The webhook was deleted.
ErrorCodePostmark API error code. 0 means the request succeeded. See the API error code table in the API description.
MessageHuman-readable result of the request.
Get webhook statistics
Returns delivery statistics for a webhook over a fixed rolling 24-hour window. Call once per webhook if a stream has several.
path Parameters
webhookIdUnique ID of the webhook.
Get webhook statistics › Responses
Webhook delivery statistics.
WebhookIdID of the webhook.
ServerIdID of the server. Field of WebhookStatistics.
MessageStreamIdMessage stream the webhook belongs to.
UrlWebhook URL.
Verification status per trigger.
The window the statistics cover.
Delivery metrics for a webhook over the window.
The same metrics broken out per trigger (for example Bounce, Delivery).
Verify a webhook
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.
path Parameters
webhookIdUnique ID of the webhook.
Verify a webhook › Responses
The verification result.
IdID of the webhook that was tested.
UrlURL that was tested.
Successtrue only if every enabled event returned HTTP 200.
Per-event results.
MessageSummary of the verification.