Docs     API     Webhooks

SimpleCirc Webhooks


Introduction

SimpleCirc Webhooks allow you to be notified about events that happen in a SimpleCirc account.

SimpleCirc can send webhook events that notify your application any time an event happens in an account. Currently notifications are limited to the following types of events.

  1. New Subscription Purchased
  2. Subscription Renewal Purchased
  3. Merchandise Purchased
  4. Subscriber Updated
  5. Subscriber Deleted
  6. Subscription Updated
  7. Subscription Deleted

You can register webhook URLs that will be notified any time an event happens in an account. When an event occurs – a new subscription is purchased for example – SimpleCirc creates an event object.

The event object contains all of the relevant information about what just happened, including the type of event and the data associated with the event. SimpleCirc then sends the event object, via an HTTP POST request, to any endpoint URLs that you have defined for a given publication. Each event can be sent to multiple webhook endpoints.


Configuration

Webhooks are configured per publication on the “Developers” tab of the publication settings page.

Click “Add Endpoint” to enter a new URL.

When a new endpoint is added it will be “disabled” by default. Once you have completed testing of the endpoint you can enable it by clicking the “toggle on” icon.

All enabled endpoints will be contacted when an event occurs.

To test the endpoint you have created click “Send Test Webhook”. You can then select the type of event notification you would like to send and deliver it to your endpoint. A dummy event will be sent and the request as well as the response will be displayed.


Receiving a webhook notification

Creating a webhook endpoint on your server is no different from creating any page on your website. With PHP, you might create a new .php file on your server.

Webhook data is sent as JSON in the POST request body. The full event details are included and can be used directly, after parsing the JSON into an event object.

PHP Example

// Retrieve the request's body and parse it as JSON:
$input = @file_get_contents('php://input');
$event_json = json_decode($input);
// Do something with $event_json
http_response_code(200); // PHP 5.4 or greater


Checking webhook signatures

To validate the events that SimpleCirc sends to your webhook URLs you can check the signature.

A signature is included in the SimpleCirc-Signature header for each event. To validate a signature you will need the Signing Secret for your publication. The Signing Secret can be found on the Developers tab of the publication settings page. Each publication has a unique Signing Signature.

In addition to the SimpleCirc-Signature header there is also a Timestamp header. You will need both for validation.

Step 1: Extract the timestamp and the signature from the headers.

Step 2: Concatenate the timestamp, the period character (.), and the actual JSON payload from the request’s body.

Step 3: Determine the expected signature by computing an HMAC with the SHA256 hash function. Use the publication’s Signing Secret as the key, and use the concatenated string from above as the message.

Step 4: Compare the computed result with the signature.


Responding to a webhook

To acknowledge receipt of a webhook, your endpoint should return a 200 HTTP status code. All other responses will indicate to SimpleCirc that you did not receive the webhook.

If your endpoint does not successfully receive a webhook for any reason, we will continue trying to send the webhook once an hour up to 5 times.


Best Practices

Before going live, test that your webhook script is working properly by sending dummy events from the settings page.

If your webhook script performs complex logic it is possible that it will timeout before acknowledging receipt to SimpleCirc. For that reason you may want to have your webhook immediately send a 200 HTTP status code and then execute the rest of your code.

Webhook endpoints might occasionally receive the same event more than once. We advise that you prevent against duplicated events.


Event Object 

{
	"created": 1536837184,
	"object": "event",
	"type": "subscription_purchased.new",
	"data": {
		"subscriber": {
			"renewal_link": "",
			"login_link": "",
			"name": "RON JOHNSON",
			"first_name": "RON,"
			"last_name": "JOHNSON",
			"company": "BIG CO",
			"email": "ron.johnson@example.com",
			"account_id": "12345678",
			"address": {
				"address_1": "123 MAIN ST",
				"address_2": "APT 4",
				"city": "ROCHESTER",
				"state": "NY",
				"zipcode": "14534",
				"country": "UNITED STATES"
			}
		},
		"subscription": {
			"subscription_id": "900000001",
			"publication_id": "999",
			"publication_name": "Bowling Digest",
			"subscription_status_code" => "A",
			"subscription_status_name" => "Active",
			"expiration_date" => "2025-01-01",
			"never_expires" => 0,
			"copies" => "1",
			"last_volume" => "17",
			"last_issue" => "2",
			"promo_code" => "SAVEBIG",
			"auto_renew" => 1,
			"auto_renew_status" => "CHARGED",
			"view_latest_issue_link" => ""
		"payment": {
			"purchase_date": "2018-09-13 07:13:04",
			"issues_purchased": "12",
			"never_expires": 0,
			"amount_due": "9.99",
			"amount_paid": "9.99",
			"tax_amount": "0.00",
			"currency": "USD",
			"utm_source" =>	"",
			"utm_medium" =>	"",
			"utm_campaign" => "",
			"utm_term" => "",
			"utm_content" => ""
		}
	}
}