# Webhooks

{% hint style="warning" %}
This page has not yet been updated for the new Laravel package.
{% endhint %}

Currently, r4nkt sends out webhooks for only one event type, but more [event types](https://docs.r4nkt.com/webhooks/events) 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](#using-jobs-to-handle-webhook-requests)
* you can [set up event listeners](#using-event-listeners-to-handle-webhook-requests)

## 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:

```php
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
    }
}
```

{% hint style="info" %}
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.
{% endhint %}

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.

```php
// 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`:

```php
/**
 * 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:

```php
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`
    }
}
```

{% hint style="info" %}
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.
{% endhint %}

The above example is only one way to handle events in Laravel. To learn the other options, read the Laravel documentation on handling [events](https://laravel.com/docs/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:

```php
$r4nktWebhookCall->payload; // returns an array
```

Or you can opt to get more specific information:

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