Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
AllPlayers webhooks implementation for external services
PHP Ruby

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib/AllPlayers
resque
tests
.gitignore
README.mkdn
composer.json

README.mkdn

AllPlayers Service Webhooks

The AllPlayers Service Webhooks act as a proxy between the defined AllPlayers API and a pre-existing third party API. When specific events occur on the AllPlayers front-end, a webhook job will be queued for processing; Based on who is listening for an event and their settings, the webhooks can be used in a versatile way to stay updated on changes that occur in the AllPlayers system. To learn more about the AllPlayers Webhooks, checkout the AllPlayers Developers Page.

Check out the following for more information:
1. How the services work


How the services work

  1. A service webhook job is submitted when a Webhook is triggered on the AllPlayers website.
  2. If the group has Webhooks enabled, the job makes a request to the specified url with the corresponding hooks data.
  3. Your external app does something with that data (sync users and groups, send emails, etc).


Steps to contributing

AllPlayers will accept custom webhook processors for production web applications. The contributions should look like our template below. To provide additional quality service and support to our users, we would additionally ask that all contributions include:

  • Documentation about what the hook does.
  • Tested code, phpunit tests if possible.
  • A URL to a logo for the service

Tests are required for all patches


Contributing

  1. Fork the project
  2. Create a new file in lib/AllPlayers/Webhooks/ called Yourservice.php along with a folder caled Yourservice, using the templates given below and following the PSR-2 Codding Standards. Check out Making your custom webhook processor and Making your custom webbhook definitions for more information.
    • Yourservice.php file is your WebhookProcessor; This is where your individual webhooks are created.
    • Yourservice folder is the collection of your uniquely defined webhooks and their actions. The actual webhook classes should be named according to the type of webhook using PSR-1 StudlyCaps (e.g. the user_creates_group webhook should be named UserCreatesGroup.php).
      • If you are defining a simplex webhook that does not correspond to a single entity, it should be called SimpleWebhook.php.
  3. Send a pull request from your fork to allplayers/service-webhooks.
  4. Once accepted, we'll add any necessary data fields to the AllPlayers front-end so people can start using your application.


Making your custom webhook processor

A webhook processor must extend WebhookProcessor and only requires the __construct() method to function. The webhook that you choose to process should be assigned to the $this->webhook variable.

<?php
/**
 * @file
 * Contains /AllPlayers/Webhooks/Yourservice.
 */

namespace AllPlayers\Webhooks;

/**
 * Yourservice WebhookProcessor where you will define your webhook actions.
 */
class Yourservice extends WebhookProcessor
{
    /**
     * Instantiate your webhooks and invoke the processing method.
     *
     * @param array $subscriber
     *   The Subscriber variable provided by the Resque Job.
     * @param array $data
     *   The Event Data variable provided by the Resque Job.
     */
    public function __construct(
        array $subscriber = array(),
        array $data = array()
    ) {
        // If you have defined a SimpleWebhook, it should look like this.
        $this->webhook = new SimpleWebhook($subscriber, $data);
        $this->webhook->process();
    }
}


Making your custom webbhook definitions

A custom webhook definition must extend Webhook and implement the WebhookInterface. A webhook only requires the __construct() method to function, if the method signature is different from Webhook::__construct(). Below is a simple webhook example which does not uniquely process the different types of webhooks available.

<?php
/**
 * @file
 * Contains /AllPlayers/Webhooks/Yourservice/SimpleWebhook.
 */

namespace AllPlayers\Webhooks\Yourservice;

use AllPlayers\Webhooks\Webhook;
use AllPlayers\Webhooks\WebhookInterface;

/**
 * A simple webhook that doesnt require unique processing for each webhook type.
 */
class SimpleWebhook extends Webhook implements WebhookInterface
{
    // If your webhook requires authentication or an alternative method of data
    // transmission, be sure to override the default values for Webhook.

    /**
     * Process the webhook data and set the domain to the appropriate URL.
     */
    public function process()
    {
        // Do no processing here, because this is a simplex webhook that dumps
        // all raw data to a single URL.
        parent::post();
    }
}


Additional Processing

Any webhook definition that requires processing of an API response, returned from calling the webhooks process() method, may implement the interface: ProcessInterface.php

<?php
/**
 * @file
 * Contains /AllPlayers/Webhooks/Yourservice/SimpleWebhook.
 */

namespace AllPlayers\Webhooks\Yourservice;

use AllPlayers\Webhooks\Webhook;
use AllPlayers\Webhooks\WebhookInterface;

/**
 * A simple webhook that doesnt require unique processing for each webhook type.
 */
class SimpleWebhook extends Webhook implements WebhookInterface, ProcessInterface
{
    ...
}

By implementing the ProcessInterface, you must also include its processResponse() method inside your custom webhook definition:

<?php
/**
 * @file
 * Contains /AllPlayers/Webhooks/ProcessInterface.
 *
 * Provides the required method signatures for additional processing.
 */

namespace AllPlayers\Webhooks;

use Guzzle\Http\Message\Response;

/**
 * The required functions for any webhook that implements the ProcessInterface.
 */
interface ProcessInterface
{
    /**
     * Process the webhook data returned from sending the webhook.
     *
     * This function should relate a piece of AllPlayers data to a piece of
     * third-party data; This information relationship will be made via the
     * AllPlayers Public PHP API.
     *
     * @param \Guzzle\Http\Message\Response $response
     *   Response from the webhook being processed/called.
     */
    public function processResponse(Response $response);
}

Note that the processResponse() method is automatically called at the end of each webhook, if your webhook implements ProcessInterface.


Credits

This webhook implementation is modeled after the GitHub Webhooks API. A huge thanks goes out to the GitHub developers and to future AllPlayers developers that work on additions to our services.

Something went wrong with that request. Please try again.