Webhook Message Schema (v2)

Subscribe Pro sends webhook notifications for each of the events documented below. The schema documented here below under each event specifies data contained in the 'data' property of the webhook event request body.

The Webhook Event Request

Each webhook notification message arrives at your application (listening for HTTP messages) in the form of an HTTP web request as follows.

NOTE: The webhook_event property contains JSON encoded as string (JSON inside a JSON string).

An example webhook event request body (v2) looks like the following:

{
  "webhook_event": "{\"id\":98989898, ... \"}",
  "webhook_event_url": "//services/v2/webhook-events/98989898"
}

An example of the decoded webhook_event property looks like the following:

{
  "id": 98989898,
  "type": "payment_profile.created",
  "data": "{\"customer_id\":9898989,\"payment_profile_id\":989898,\"customer\":{\"id\":9898989, ... }}",
  "destinations": [
    {
      "id": 9191919191,
      "endpoint": {
        "id": 91919191,
        "channel": "url",
        "status": "enabled",
        "all_subscribed_event_types": false,
        "subscribed_event_types": "{\"3\":\"payment_profile.created\",\"4\":\"payment_profile.updated\",\"5\":\"payment_profile.redacted\"}",
        "created": "2020-06-04T12:24:44+0000",
        "updated": "2020-06-04T12:24:49+0000"
      },
      "status": "delivered",
      "last_attempt": "2020-07-19T15:29:23+0000"
    }
  ],
  "created": "2020-07-19T15:29:21+0000",
  "updated": "2020-07-19T15:29:21+0000"
}

NOTE: The data property contains JSON encoded as string (JSON inside a JSON string). Yes, this is double encoded as JSON inside JSON string because the data property is inside the webhook_event property.

An example of the decoded data property looks like the following:

{
  "customer_id":9898989,
  "payment_profile_id":989898,
  "customer":{
    "id":9898989,
    ...
    "created":"2020-07-19T15:29:11+0000",
    "updated":"2020-07-19T15:29:11+0000",
    "subscription_count":0,
    "active_subscription_count":0,
    "trial_subscription_count":0,
    "active_subscribed_qty":0
  },
  "payment_profile":{
    "id":989898,
    "customer_id":9898989,
    ...
    "billing_address":{
      ...
      "created":"2020-07-19T15:29:21+0000",
      "updated":"2020-07-19T15:29:21+0000"
    },
    "created":"2020-07-19T15:29:21+0000",
    "updated":"2020-07-19T15:29:21+0000"
  }
}

Who Made the Change

When Subscribe Pro knows who made a change, the data property of the event also contains a _meta object with the same "changed by" information recorded in the subscription history, except that the identity of Subscribe Pro support staff is replaced by the label Subscribe Pro Support. Your own Classic users, New Merchant App users, customers and API clients are always identified. If the actor is not known, _meta is omitted. Existing data properties are not affected, so consumers that ignore unknown properties need no changes.

{
  "subscription_id": 5511002,
  "customer": { "id": 6590083, "...": "..." },
  "subscription": { "id": 5511002, "...": "..." },
  "_meta": {
    "changed_by": {
      "changed_by_type": "customer_via_api",
      "changed_by": "Customer Cleo Customer",
      "customer_id": "6590083",
      "customer_email": "[email protected]",
      "customer_name": "Cleo Customer",
      "client_public_id": "0f1e2d3c-example",
      "client_name": "My Subscriptions Widget"
    }
  }
}

The event types that carry _meta are customer.subscribed, customer.cancelled, subscription.created, subscription.updated, subscription.cancelled, subscription.status_change, group_subscription.created and group_subscription.updated. Other event types do not include it yet.

_meta.changed_by.changed_by_type is one of:

Value	Who made the change	Other properties
`app_user_auth`	A user of the New Merchant App	`app_user_id`, `app_user_name`, `app_user_email`
`user_auth`	A user of the Classic app. A user of your own organization is identified, while Subscribe Pro support staff, for example working in Classic on your behalf, are not	Your own users: `user_id`, `user_name`, `user_email`. Subscribe Pro staff: none, and `changed_by` is `Subscribe Pro Support`
`customer_auth`	The customer, using their own access token	`customer_id`, `customer_email`, `customer_name`
`customer_via_api`	An API client acting for a customer, using `_meta` on the API request	`customer_id`, `customer_email`, `customer_name`, `client_public_id`, `client_name`
`admin_user_via_api`	An API client acting for one of your admin users, using `_meta` on the API request	`user_external_id`, `admin_email`, `admin_name`, `client_public_id`, `client_name`
`admin_user_via_api_customer_scope`	An admin user acting through a customer scoped token	`customer_id`, `customer_email`, `customer_name`, `user_external_id`, `admin_email`, `admin_name`
`api`	An API client that did not say who is acting	`client_public_id`, `client_name`
`customer`, `admin_user`	A customer or admin user named in `_meta`, without API client details	As for `customer_via_api` and `admin_user_via_api`
`platform`	Subscribe Pro automation, for example expiring or failing subscriptions	None

The My Subscriptions widget and your own API calls can say who is acting by sending _meta with the request, for example {"_meta": {"changed_by": {"customer": {"customer_id": "6590083", "email": "[email protected]", "full_name": "Cleo Customer"}}}}. Use customer with customer_id, email and full_name, or admin with user_id, email and full_name. Only these properties are used, other properties are ignored, and each value is limited to 255 characters. The values are reported as supplied, so they are only as trustworthy as the client that sent them.

All Webhook Event Types

Customer Event Types

Event	Type code
Customer Subscribed	`customer.subscribed`
Customer Cancelled	`customer.cancelled`

Payment Profile Event Types

Event	Type code
Payment Profile Created	`payment_profile.created`
Payment Profile Updated	`payment_profile.updated`
Payment Profile Redacted	`payment_profile.redacted`

Subscription Event Types

Event	Type code
Subscription Created	`subscription.created`
Subscription Updated	`subscription.updated`
Subscription Cancelled	`subscription.cancelled`
Subscription Status Changed	`subscription.status_change`
Subscription Trial Converted	`subscription.trial.converted`
Subscription Email Triggered	`subscription.email`

Payment Transaction Event Types

Event	Type code
Payment Transaction Updated	`payment_transaction.updated`

Group Subscription Event Types

Event	Type code
Group Subscription Created	`group_subscription.created`
Group Subscription Updated	`group_subscription.updated`

Customer Events

Customer Subscribed Event

Event type: customer.subscribed

Notification is sent when a customer subscribes. This means the customer previously had 0 Active subscriptions and at least 1 Active subscription has just been added.