Webhooks

Apps can use webhooks to execute code after a certain event happens on the platform, for example after a new order or when customer data is modified.

Instead of periodically pulling objects via the API, the app can register webhooks which send an http(s) request to the app when the registered event occurs. This is easer to implement, uses less resources for API calls, allows for fast response after events and over all helps to create more robust apps.

Webhooks are scoped to the app and company they are bound to. A webkook does not receive events for other companies and other apps don’t influence triggering registered events.

Structure of a Webhook

If a webhook was registered to a certain event and the event happens, Flickrocket send a webhook notification to the specified URL. The notification contains a JSON payload with information which can be used to identify the event as well as event specific data and a signature which can be used to verify the validity of the notification.

As an example, the following JSON is sent as payload of the of the order/create webhook.

{
 "company_id": 1202,
 "producer": "shop",
 "scope": "order/create",
 "data": {
 "type": "order",
 "id": "267227"
 },
 "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Webhook Authentication

Each webhook payload includes a hash value which can be used to validate that the webhook originates from Flickrocket.

To verify this, all key/value pairs of the JASON with exception of the hash need to be concatenated from the beginning to the end and then a SHA256 hash with using the App Secret as salt is calculated.

Respond to Webhook Callbacks

To acknowledge that you received the webhook without issue, your server should return a 200 HTTP status code. Any other information you return in the request headers or request body will be ignored. Any response code outside the 200 range, including 3_xx_ codes, will indicate to us that you did not receive the webhook. When a webhook is not received (for whatever reason), we will attempt to callback as described just below.

Callback Retry Mechanism

Webhooks will do their best to deliver the events to your callback URI. The dispatcher will attempt several retries until the maximum retry limit is reached, as follows:

Whenever a webhook gives a non-2_xx_ response, or times out, the app will be blocked for 60 seconds.
Webhooks created during that 60-second block will be queued up to send on the next scheduled retry attempt after the block expires, so that webhooks are not lost.

The dispatcher will then attempt several retries (at increasing intervals) until the maximum retry limit is reached, as follows:

Retry Intervals

60 seconds after the most recent failure
180 seconds after the most recent failure
300 seconds after the most recent failure
600 seconds after the most recent failure
900 seconds after the most recent failure
1800 seconds after the most recent failure
3600 seconds after the most recent failure
7200 seconds after the most recent failure
21600 seconds after the most recent failure
50400 seconds after the most recent failure
86400 seconds (24 hours) after the most recent failure

After the final retry attempt above (cumulatively, 48 hours after the first delivery attempt), the webhook will automatically be deactivated, and we will send an email to the developer’s email address registered on the subscribing app. Should you wish to reactivate the hook, you can set the is_active flag back to true via a PUT request to the hooks resource.

List of Webhook Events

Webhooks can be registered for the following events:

Events	Topics
Customer	customer/create, customer/update This event is triggered when a new customer is created (e.g. during an order) or when customer data is updated.
Subscriber	subscriber/create, subscriber/update This event is triggered when a new subscriber is created, typically when someone signs up to a subscription or when subscriber data is updated.
Groupmember	groupmember/create, groupmember/update This event is triggered when a new group member is created, typically when someone is added to an access group or when a group member’s data is updated.
Newsrecipient	newsrecipient/create, newsrecipient/update This event is triggered when a new newsletter recipient is created, typically when someone signs up to a newsletter or when recipient data is updated.
Order	order/create This event is triggered when a new order is generated.
Product	product/create, product/delete, product/update This event is triggered when a new product is created, modified or a product is deleted.
App	app/uninstalled, app/update This event is triggered when an app is uninstalled, app permissions were removed.

What you can do with Webhook

The Flickrocket API lets you do the following with the Webhook resource. More detailed versions of these general actions may be available:

GET /admin/webhooks.json

Receive a list of all Webhooks

GET /admin/webhooks/#{id}.json

Receive a single Webhook

POST /admin/webhooks.json

Create a new Webhook

PUT /admin/webhooks/#{id}.json

Modify an existing Webhook

DELETE /admin/webhooks/#{id}.json

Remove a Webhook from the database

Webhook properties

address	"address": "https://someapp.com/uninstall" The URI where the webhook should send the POST request when the event occurs.
id	"id": 901431826 The unique numeric identifier for the webhook.
topic	"topic": "app/uninstalled" The event that will trigger the webhook. Valid values are listed above.
updated_at	"updated_at": "2012-09-28T11:50:07-04:00" The date and time when the webhook was updated.

Get a list of all webhooks for your shop

GET /admin/webhooks.json

View Response

Get a single webhook by its id

GET/admin/webhooks/4759306.json

View Response

Create a new webhook

POST /admin/webhooks.json

{
 "webhook": {
 "topic": "order\/create",
 "address": "http:\/\/whatever.hostname.com\/",
 "format": "json"
 }
}

View Response

Update a webhook's topic and/or address URIs

Change a webhook so that it POSTs to a different address:

PUT /admin/webhooks/#{id}.json

{
 "webhook": {
 "id": 4759306,
 "address": "http:\/\/somewhere-else.com\/"
 }
}

View Response

Delete a webhook

DELETE/admin/webhooks/4759306.json

View Response

Troubleshooting

Below are remedies for certain errors commonly encountered with webhooks:

Not Receiving the POST Requests to My Callback URI

As noted above, if your app does not return an HTTP 2_xx_ to Flickrocket upon receipt of the POST request to the callback URI, Flickrocket considers it a failure. Flickrocket will keep trying for a little over 48 hours. At the end of that time, Flickrocket sends an email to the email address set during app registration and flips the is_active flag to false.

You can proactively check to make sure that everything is OK by periodically making a GET request and checking the is_active flag.

If you receive an email or discover that the is_active flag has been flipped to false, try the following:

• Check to see if your app is responding to the POST request with something other than HTTP 200.

• Check to make sure that your server has a valid TLS/SSL setup. One way to do this is by visiting the following website: https://sslcheck.globalsign.com. Any of the following will cause the TLS/SSL handshake to fail:

o Self-signed certificate.

o Host name of the certificate does not match the server’s DNS.

o Your server’s key or trust store has not been loaded up with the intermediate cer-tificates necessary to establish the chain of trust.

Once you have resolved the issue preventing the connection, send a PUT request to flip the is_active flag back to true. This will cause Flickrocket to start trying to send the POST requests to your callback URI again.

Not Receiving an HTTP 201 Response after Sending POST to Create Webhook

After sending a POST request to create a webhook, you should get an HTTP 200 back. If you do not, check your TLS/SSL setup and the HTTP header in your request. The requirements for the HTTP header are discussed in the introduction above.