Webhooks

This page has not yet been updated for the new Laravel package.

Currently, r4nkt sends out webhooks for only one event type, but more event types may come in the future.

R4nkt signs all requests that hit your game's specified webhook url. This package will automatically verify each webhook request's signature. If any signature is not valid, the request was likely not sent by r4nkt and will be rejected and a R4nkt\R4nktWebhooks\WebhookFailed exception will be thrown.

Unless something is wrong, this package will respond with a status code of 200 to all webhook requests. This will prevent r4nkt from resending the same event.

When using this package, you have two ways to handle incoming webhook requests:

• you can opt to queue a job

• you can set up event listeners

Using Jobs to Handle Webhook Requests

If you want to do something when a specific event type comes in you can define a job that does the work. Here's an example of such a job:

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use R4nkt\LaravelWebhooks\R4nktWebhookCall;

class HandleBadgeEarnedCheck implements ShouldQueue
{
    use InteractsWithQueue, Queueable, SerializesModels;

    /** @var  \R4nkt\LaravelWebhooks\R4nktWebhookCall */
    public $webhookCall;

    public function __construct(R4nktWebhookCall $webhookCall)
    {
        $this->webhookCall = $webhookCall;
    }

    public function handle()
    {
        // do your work here

        // you can access the payload of the webhook call with $this->webhookCall->payload
    }
}

You are advised to make this job queueable. This will minimize the webhook request response time, allow you to handle more r4nkt webhook requests, and help avoid timeouts.

Once your job is created, it must be registered in the jobs array in the r4nkt.php config file. The key should be the name of the r4nkt event type and the value should be the job's fully qualified class name.

// config/r4nkt.php

'jobs' => [
    'badgeEarned' => \App\Jobs\R4nktWebhooks\HandleBadgeEarnedCheck::class,
],

Using Event Listeners to Handle Webhook Requests

Upon receiving a valid webhook request, this package will fire a r4nkt-webhooks::* event. So, you can define event listeners to listen for any events this package might fire.

The event payload will be the instance of R4nktWebhookCall that was created for the incoming request.

Here is an example of how you can listen for an event by registering a listener in the EventServiceProvider:

/**
 * The event listener mappings for the application.
 *
 * @var    array
 */
protected $listen = [
    'r4nkt-webhooks::badgeEarned' => [
        App\Listeners\MailOperators::class,
    ],
];

Here's an example of such a listener:

namespace App\Listeners;

use Illuminate\Contracts\Queue\ShouldQueue;
use R4nkt\LaravelWebhooks\R4nktWebhookCall;

class BadgeEarned implements ShouldQueue
{
    public function handle(R4nktWebhookCall $webhookCall)
    {
        // do your work here

        // you can access the payload of the webhook call with `$webhookCall->payload`
    }
}

You are advised to make this event listener queueable. This will minimize the webhook request response time, allow you to handle more r4nkt webhook requests, and help avoid timeouts.

The above example is only one way to handle events in Laravel. To learn the other options, read the Laravel documentation on handling events.

Using the Webhook Call Object

As already noted, your events or jobs will receive an instance of R4nkt\LaravelWebhooks\R4nktWebhookCall.

You can access the raw payload by calling:

$r4nktWebhookCall->payload; // returns an array

Or you can opt to get more specific information:

$r4nktWebhookCall->type(); // returns the webhook type, e.g. `badgeEarned`
$r4nktWebhookCall->dateTime(); // returns the date/time (string, Ymdhis) when r4nkt generated this webhook call