Post-backs

We strongly recommend using Webhooks instead of Post-Backs. Webhooks have more features and can be easier to use.

What is a Post-Back?

In order to notify your application of events that happen inside the Chargify application, such as new signups and accounts entering dunning, Chargify can “post-back” to your application. Postbacks are configured on the “Settings” tab for each site.

What is the Subscription update Post-Back?

When subscriptions change in a way that may affect how you deal with the subscription owners, we can send you a post back that contains the IDs of all of the affected subscriptions. The Post-back data will be a JSON encoded array of IDs of the subscriptions that have changed since you were last successfully notified, such as:

[201, 345, 468]

This would indicate that the subscriptions with IDs 201, 345, and 468 have changed in some way that you may care about (i.e. the state has changed, there was an upgrade or downgrade, etc.)

Unless you return an HTTP status code in the 4xx or 5xx range, we will assume that you successfully received and accepted the update. If we receive an HTTP Status Code response in the 4xx or 5xx range, we will continue to notify you about the same subscriptions sent in the update.

What events trigger a Post-Back?

Any change to any of the following subscription attributes will trigger a Post-Back:

  • state: A state change might change customer access rights
  • next_assessment_at: A change to this date might affect site subscription caching
  • product_id: A change here would indicate a up-/down-/cross-grade

Common Examples (not a complete list):

  • Subscription changes State; ie, from “active” to “past_due” because their credit card got declined
  • Subscription changes product ID; ie, customer upgrades from your “Plan A” to “Plan B”

For more details about these parameters, see the documentation for the Subscriptions resource.

Note that changes to the state attribute may occur as the state “passes through” several states and lands in another. So, if you have a subscription that you know to be in the active state, you may receive a Post-Back when the subscription goes through normal, periodic, assessment and find that, by the time you fetch the subscription information via the API, the subscription is still in the active state. This is a valid case, and may indicate that the subscription transitioned to the special ‘assessing’ state and came out on the other side still ‘active’, e.g. the payment for the subscription succeeded.

When you also watch (and record) the ‘next_assessment_date’, you can gain valuable insight in to what is happening with the subscription. For example: If you receive a post-back about a subscription, and it has remained active but the next_assessment_date has jumped forward, then it has renewed successfully.

When are they sent?

There is a short delay after the triggering event, up to about 15 minutes, before the post-back is sent.

If we have trouble sending post-backs to your server (ie, we receive error codes from your server), then we will “back off” on sending to you… we will delay 1 hour, then 2 hours, then 4 hours, etc, until we are again able to successfully send post-backs to you. This means that if there was a problem on your end, it may be a number of hours before we will try again. Once we send another successful post-back, our system will reset the delay to zero.

Receiving the Post-Back

Note that this data is sent as the content of the response, not in any query or form parameters. If you’re using Rails, the data is parsed for you and is inside of the params hash under the ‘_json’ key:

params['_json']

This example controller may help you get started:


class Chargify::SubscriptionsController < ApplicationController
  def update  
    subscription_ids = params['_json']
    #Rails.logger.debug("SUB IDS: #{subscription_ids.inspect}")
    begin
      subscription_ids.each do |id|
        # Process updated subscriptions here
        Rails.logger.debug("SUB ID: #{id}")
      end
      respond_to do |format|
        format.json { head :ok }
      end
    rescue # watch out, this will rescue everything! You may want to be more selective...
      respond_to do |format|
        format.json { head :internal_server_error }
      end
    end
  end
end

# suggested corresponding named route for routes.rb
# map.chargify_subscriptions '/chargify/subscriptions/:action.:format', :controller => 'chargify/subscriptions'

Not receiving Post-backs?

If you’ve set up everything correctly according to the instructions below, and you’re not receiving post-backs, the most common reason is… if your server ever returned error codes to our servers when we first tried to send post-backs to you, then we will increase the cycle time between attempts. So, if we get back errors a few times, the cycle time for retry can stretch into hours or days. If this has happened to you, please submit a ticket and one of our devs can reset the cycle time for you.