Webhooks Version 2

Version 2 of Piano webhooks are sent on access and content locking events - i.e. there is not a subscription_ended event anymore. Go here for an overview of how the webhooks mechanism works in Piano.

There are several updates to the exponential backoff in version 2 which are described here.

The three types of access events that trigger webhooks are the three things that can happen to access: granted, modified, revoked.

The two types of content locking events are lock and unlock.

Note: The content locking events are only sent if you are using the Piano algorithmic paywall. If you are not using the algorithmic paywall, only access events will be sent.

Triggering Events

Access Granted: These are all of the events that result in new access. new_purchase, payment_verified, free_access_granted, free_promo_redemption, and new_registration_conversion.

Access Modified: These are all of the events that indicate access has been modified. subscription_updated, subscription_auto_renewed, access_modified, and grace_period_extension.

Access Revoked: These are all of the events the indicate revoked access. access_revoked, subscription_auto_renewed_failure, subscription_canceled, subscription_expired, and access_ended.

Content Algorithm: These event indicates that the algorithm has determined that some piece of content needs locking or unlocking. The possible events are lock and unlock.

Format

The format of the webhook has been standardized across all webhook events. There are two fields that you should key off of to determine what has happened - the type field, which indicates the high-level event that has occurred, and then the event field which gives you more detail about the specific event.

Access Granted

On access granting events, the type field will be access_granted and the event field will be one of the following fields.

{
    "version": 2,
    "type": "access_granted",
    "event": "(new_purchase|payment_verified|free_access_granted|free_promo_redemption|new_registration_conversion)",
    "access_id": "6iAB241bfNdkez",
    "expires": 1434514901,
    "rid": "PREMIUM_ACCESS",
    "uid": "43097265",
    "aid": "87jJKj3jf3"
}

Access Modified

On access granting events, the type field will be access_modified and the event field will be one of the following fields.

{
    "version": 2,
    "type": "access_modified",
    "event": "(subscription_updated|subscription_auto_renewed|access_modified|grace_period_extension)",
    "access_id": "6iAB241bfNdkez",
    "expires": 1434514901,
    "rid": "PREMIUM_ACCESS",
    "uid": "43097265",
    "aid": "87jJKj3jf3",
}

Access Revoked

On access revoking events, the type field will be access_revoked and the event field will be one of the following fields.

{
    "version": 2,
    "type": "access_revoked",
    "event": "(access_revoked|subscription_auto_renewed_failure|access_ended|subscription_canceled|subscription_expired)",
    "access_id": "6iAB241bfNdkez",
    "expires": -1,
    "rid": "PREMIUM_ACCESS",
    "uid": "43097265",
    "aid": "87jJKj3jf3",
}

Content Algorithm

On algorithmically triggered events, the type field will be content_algorithm and the event field will be either lock or unlock. The content_id field indicates which piece of content should be locked or unlocked, and is the content_id that is local to your content management system.

{
  "version": 2,
  "type": "content_algorithm",
  "event": "(lock|unlock)",
  "aid":"87jJKj3jf3",
  "timestamp":1428349417,
  "content_id" : "the unique post id",
}

Access Ended

Piano has introduced the access_ended event in version 2 of webhooks. The access_ended event only fires whenever access “naturally” expires, meaning that it wasn't due to any user, publisher, admin, or system action. This means that it is never sent for access that is associated with subscriptions, since the subscription renewal process handles sending the access_revoked events of subscription_auto_renewed_failure and subscription_expired.

Every hour, Piano will queue up any access that has ended and meets the following criteria:

  • Has expired in the last 2 days
  • Is not associated with a subscription
  • Does not have an access_ended webhook already queued to be sent, or the last access_ended webhook was last sent prior to the current access expiration, to handle access that has been modified after the access_ended webhook was sent

The access ended event is never sent for access that is associated with subscriptions.

Subscriptions either fail to renew or expire due to auto-renew being turned off, both of which are system-level events that trigger the access_revoked webhook in real time. The access ended event is only sent for “naturally” expiring access.

Updates to Exponential Backoff on Failure

Additionally with the introduction of webhooks version 2, we have made improvements to how we notify you and how long we will continue trying to send webhooks.

  • 7-day deactivation window, increased from 2 days
  • Send hourly emails during failure, in addition to the emails that are sent after 6 failures and 20 failures
  • Additional emails sent 24 hours, 8 hours, and 1 hour before deactivation

Triggering Events

Here is a full list of all webhook events that will get sent by Piano and whether they are user-triggered, publisher-triggered, or system-triggered.

Access Granted

Type Event User Publisher System Notes
access_granted new_purchase Y N N Sent when a user makes a purchase where there was a financial transaction that took place. For free trials, the payment_verified event is sent.
access_granted payment_verified Y N N Sent when a user signs up for a free trial. This event is only sent for free trials where the user will eventually be charged. If the user has a promo code that gives them 100% off of a fixed-time purchase, the free_promo_redemption event is sent instead.
access_granted free_promo_redemption Y N N Sent when a user redeems a promo code for 100% off of a fixed-time purchase. If a user redeems a promo code where there is a transaction that takes place (or will take place in the case of a free trial), either the new_purchase or payment_verified event is sent.
access_granted new_registration_conversion Y N N Sent when a user is granted access in return for registering on your website.
access_granted free_access_granted N Y N Sent when a publisher dashboard user grants access to a user.

Access Modified

Type Event User Publisher System Notes
access_modified subscription_updated N Y N Sent when a publisher updates the next bill date on a user's subscription.
access_modified subscription_auto_renewed N N Y Sent when the Piano system successfully auto-renews a user's subscription.
access_modified subscription_manually_renewed Y Y N Sent when a user manually renews their subscription, or when a publisher manually renews a user's subscription on their behalf.
access_modified access_modified N Y N Sent when a publisher modifies a user's non-subscription-based access. Access that is associated with a subscription is modified by updating the next bill date, which triggers the subscription_updated webhook.
access_modified grace_period_extension N N Y Sent when the Piano system grants additional days of access to a user whose subscription we are unable to automatically renew. After the grace period is over, we send the subscription_auto_renewed_failure event.

Access Revoked

Type Event User Publisher System Notes
access_revoked subscription_auto_renewed_failure N N Y Sent when Piano is unable to charge a user's credit card to renew their subscription, and there is no grace period or the grace period has ended.
access_revoked subscription_canceled Y Y N Sent when a user cancels their subscription, or when Piano cancels a user's subscription on their behalf.
access_revoked subscription_expired N N Y Sent when Piano attempts to renew a user's subscription and determines that auto-renew is turned off.
access_revoked access_ended N N Y Sent when Piano determines that non-subscription-based access has ended. See the Access Ended section for more details on how and when this gets sent.