# Subscription change webhook

## What is a subscription change?

A subscription change is recorded when an email address is added or removed from a Message Stream's Suppression list. An email address is added to a Suppression List after a Hard Bounce, Spam Complaint, Unsubscribe, or Manual Suppression. A manual suppression is created in Postmark's UI or [using the API](/api/suppressions).

An email address is removed from the suppression list manually by choosing an address to reactivate in Postmark's UI or [using the API](/api/suppressions#delete-a-suppression).

You can also get the suppression list [using the API](/api/suppressions).

_Note: The datetime for the ChangedAt field is in ISO 8601 format._

### What can I use subscription change events for?

- Use the webhook in place of the bounce and spam complaints webhook to receive notifications on inactive addresses.

- Maintain a suppression list of your own.

- Notify a user in your app their address is currently active/inactive.

## Create a new webhook

### Using the Postmark website

When logged into Postmark, select the Server, the Message Stream, and then go to the **Webhooks** tab. Choose **Add webhook** and input your webhook URL in **Webhook URL** and then select the **Subscription Change** checkbox.

### Using the API

You can modify the SubscriptionChange field using the Webhooks API [to edit an existing Webhook](/api/webhooks#edit-a-webhook). You can also use the Webhooks API [to create webhooks](/api/webhooks#create-a-webhook) and set the SubscriptionChange field at the same time. After setting the URL, verify the webhook so you know it's reachable before events start flowing. See [Verifying your webhook](/webhooks/webhooks-overview#verifying-your-webhook).

## Event data

An example of the full JSON document that would be POSTed to your webhook URL is to the right.

- The SuppressSending field will inform whether that was a deactivation or reactivation.

- MessageID is _null_ for Manual Suppressions with Origin value of Customer or Admin and Reactivations.

- Possible SuppressionReason values are: HardBounce, SpamComplaint, or ManualSuppression.

- If a recipient unsubscribes, they will be suppressed with the SuppressionReason of ManualSuppression.

- The SuppressionReason and Tag fields are null, while the Metadata field is an empty object when SuppressSending = false (reactivation).

- The Origin field shows where that originated from. e.g.: Recipient, Customer, Admin

- ChangedAt—timestamp of when the subscription changed.

### Example JSON webhook data

```js
{
  "RecordType": "SubscriptionChange",
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "ServerID": 23,
  "MessageStream": "outbound",
  "ChangedAt": "2026-11-05T16:33:54.9070259Z",
  "Recipient": "margareth@nasa.com",
  "Origin": "Recipient",
  "SuppressSending": true,
  "SuppressionReason": "HardBounce",
  "Tag": "welcome-email",
  "Metadata": {
    "PropA": "some value",
    "PropB": "some value"
  }
}
```

## Testing events

If you’re developing on your local machine or don’t have a public URL for your API, the cURL request example below sends a test webhook to your service. Replace _&lt;your-webhook-url>_, run the command, and verify it accepts and processes the event as expected.

### Example cURL

```bash
curl <your-webhook-url> \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "RecordType": "SubscriptionChange",
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "ServerID": 23,
  "MessageStream": "outbound",
  "ChangedAt": "2026-11-05T16:33:54.9070259Z",
  "Recipient": "margareth@nasa.com",
  "Origin": "Recipient",
  "SuppressSending": true,
  "SuppressionReason": "HardBounce",
  "Tag": "welcome-email",
  "Metadata": {
    "PropA": "some value",
    "PropB": "some value"
  }
}'
```
