Webhooks - Examples

Installing webhooks is simple. It takes three simple steps:

1) Create a Webhook Script

The purpose of this step is to create a URL that we can provide to SugarOutfitters. One way to do this is to create a simple script and upload it to a web-accessible server. You can do this in any web language or framework. For this walkthrough we’ll be using PHP.

Create script.php. We"ll start with this simple script and add more to it soon:

<?php

echo “Hello, world!”;

Now save and upload your script to a web-accessible server. For example sake, I uploaded mine to http://yourwebsite.com/path/to/webhooks/script.php

2) Enable Webhooks on SugarOutfitters

Now that we have a valid URL to your script, you need to go to the “Manage Add-ons” page on SugarOutfitters. Once there, click the add-on you’d like to enable webhooks for and find the “Webhooks” tab. Provide your URL and click “Test & Save”. This will send an HTTP Request to your URL. If there is a successful 200 HTTP Response, it’ll tell you “The webhook passed the test!” and you’re all set!

3) Write code for Webhooks

In the sample code below, there are three primary things you need to make sure work:

1. Retrieve the data sent from SugarOutfitters - Webhook events are sent to your webhooks script via HTTP POST Requests. The body of the response is a JSON string. Simply grab the body of the request and decode it to a PHP object. (Lines 3-7)

2. Now that we’ve received the event data, we need to figure out what event just occurred and route it appropriately. The response represents an event object. Determining which event occurred is as simple as looking at what the $response->webhook value is. To handle specific events, simply create a switch/case statement or if/else statements. Whatever is convenient for you. You can implement as few or as many of the available events as you like. (Lines 11-32)

3. Lastly, write your custom code. For each event you are implementing, write the custom code you’d like to be executed when the events occur. To keep things clean, I created a single static method for each of the events and the corresponding class is below, but you can implement this however you like. This is only one way to do it. We’ve created the platform to be as simple and flexible as possible.

Example webhook script:

<?php

// get the webhook response
$body = @file_get_contents("php://input");

// decode the json data into a php object
$response = json_decode($body);

// the webhook property tells us exactly which webhook event was fired
// so let"s create a case for a few webhooks
switch ($response->webhook)
{
    case "sale_new":
        // Someone purchased your add-on, your code goes here
        SugarOutfittersHelper::sale_new($response);
        break;

    case "case_created":
        // A support case was created, your code goes here
        SugarOutfittersHelper::case_created($response);
        break;

    case "usercount_changed":
        // The number of users has changed for a customer"s license key, your code goes here
        SugarOutfittersHelper::usercount_changed($response);
        break;

    case "question_created":
        // A question has been asked about your add-on, your code goes here
        SugarOutfittersHelper::question_created($response);
        break;
}

class SugarOutfittersHelper
{
    public static function sale_new($response)
    {
        // get the data from the event
        // a new sale gives you the addon, lineitem, member and licensekey objects related to the purchase
        $addon = $response->data->addon; // the addon that was purchased
        $lineitem = $response->data->lineitem; // we give you the lineitem because you may have multiple purchase plans for an add-on
        $member = $response->data->member; // your new customer!
        $licensekey = $response->data->licensekey; // if you"re using SugarOutfitters lincense keys, the details of the license key are listed here

        // write whatever logic you need to kick off a new sale (below are made up methods...)
        alert_billing_of_new_purchase($addon->name, $lineitem->plan_name, $member->name, $member->email);
        start_new_customer_onboarding_process();
    }

    public static function case_created($response)
    {
        // get the data from the event
        // a case created event
        $case = $repsonse->data->case;
        $member = $response->data->member;
        $addon = $response->data->addon;

        // write whatever you want to occur when a new case is created (below are made up methods...)
        create_new_case_in_sugarcrm($case->id,$case->subject,$case->description,$member->email);
        send_case_to_jira($case->id,$case->subject,$case->description,$member->email);
    }

    public static function usercount_changed($response){}
    public static function question_created($response){}

There are a few fundamental things to keep in mind as you’re implementing Webhooks:

1) Webhook URLs are specific to individual Add-ons

You are able to provide a unique Webhook URL for each individual add-on. If you sell multiple add-ons, you can have them all point to the same webhook script if you like. If you do this, you will need to be sure to check which add-on the event occurred on before taking any action. Too make this easy, see the next point...

2) Every Webhook Event is delivered with an Add-on object that is specific to the Add-on the event occurred to.

In the example code above, if you were to use a single webhook script for multiple add-ons, all you would need to do is check the $response->data->addon->id or $response->data->addon->name to determine which exact add-on the event occurred to.